KRB5_GET_CREDS(3)

✨ KRB5_GET_CREDS ✨

okay bestie, pull up a chair, because today we're reading a Library Functions Manual page and it's lowkey the most useful thing ever 💖 it's all about grabbing credentials from the KDC, and there's a whole little family of functions here that work together like the friend group in a coming-of-age movie 🫶

🌸 NAME 🌸

krb5_get_creds, krb5_get_creds_opt_add_options, krb5_get_creds_opt_alloc, krb5_get_creds_opt_free, krb5_get_creds_opt_set_enctype, krb5_get_creds_opt_set_impersonate, krb5_get_creds_opt_set_options, krb5_get_creds_opt_set_ticket — get credentials from the KDC 👑

💜 LIBRARY 💜

Kerberos 5 Library (libkrb5, -lkrb5) — link it or perish, no cap 🔗

🎀 SYNOPSIS 🎀

#include <krb5.h>

krb5_error_code
krb5_get_creds(krb5_context context, krb5_get_creds_opt opt,
    krb5_ccache ccache, krb5_const_principal inprinc,
    krb5_creds **out_creds);

void
krb5_get_creds_opt_add_options(krb5_context context,
    krb5_get_creds_opt opt, krb5_flags options);

krb5_error_code
krb5_get_creds_opt_alloc(krb5_context context, krb5_get_creds_opt *opt);

void
krb5_get_creds_opt_free(krb5_context context, krb5_get_creds_opt opt);

void
krb5_get_creds_opt_set_enctype(krb5_context context,
    krb5_get_creds_opt opt, krb5_enctype enctype);

krb5_error_code
krb5_get_creds_opt_set_impersonate(krb5_context context,
    krb5_get_creds_opt opt, krb5_const_principal self);

void
krb5_get_creds_opt_set_options(krb5_context context,
    krb5_get_creds_opt opt, krb5_flags options);

krb5_error_code
krb5_get_creds_opt_set_ticket(krb5_context context,
    krb5_get_creds_opt opt, const Ticket *ticket);

🌈 DESCRIPTION 🌈

okay so krb5_get_creds() is the main character here 💅 it fetches the credentials that opt is asking for — and the way it does that is so smart: first it peeks inside ccache, and if the credential isn't there (the page literally says "it doesn't exists", we don't make the rules, we just report them 🙈), it goes and fetches that credential from the KDC using the krbtgts in ccache. The credential comes back to you in out_creds, and bestie — you have to free it with krb5_free_creds(). Don't ghost your memory, it's not the vibe 🫶

The structure krb5_get_creds_opt is what controls the behavior of krb5_get_creds(). It's opaque to consumers — so you can't just reach in and touch it, you set what's inside using the accessor functions ✨ and here's the tea: all the accessor functions make copies of the data you pass in, so external consumers should free that memory before calling krb5_get_creds(). Clean up after yourself, queen 👑

The krb5_get_creds_opt structure gets allocated with krb5_get_creds_opt_alloc() and freed with krb5_get_creds_opt_free(). And the free function is an overachiever — it also frees the content of the structure that the accessor functions set. So thorough. So iconic 🌟

krb5_get_creds_opt_add_options() and krb5_get_creds_opt_set_options() add and set options onto the krb5_get_creds_opt structure. (Yes, the original has a lil space before that period. We stan a quirky typo 😭)

The possible options you can set are:

• KRB5_GC_CACHED — only check the ccache, don't go out on the network to fetch a credential. staying home era 🏠
• KRB5_GC_USER_USER — request a user to user ticket. and heads up: this option does not store the resulting user to user credential in the ccache 🚫
• KRB5_GC_EXPIRED_OK — returns the credential even if it is expired. the default behavior is to try to refetch the credential from the KDC, so this one is the "nah, expired is fine, give it here" button ⏰
• KRB5_GC_NO_STORE — do not store the resulting credentials in the ccache 🗑️

krb5_get_creds_opt_set_enctype() sets the preferred encryption type of the application. but listen — don't set this unless you have to, because if there's no match in the KDC, the function call will fail. it's giving "playing with fire" 🔥

krb5_get_creds_opt_set_impersonate() sets the principal to impersonate. it returns a ticket that has the impersonation principal as a client and the requestor as the service. and note this carefully: the requested principal has to be the same as the client principal in the krbtgt. matching sets only, bestie 👯

krb5_get_creds_opt_set_ticket() sets the extra ticket used in the user-to-user or contrained delegation use case. (yes it says "contrained" in the original and we are respectfully leaving it exactly as written 💀)

🦋 SEE ALSO 🦋

krb5(3), krb5_get_credentials(3), krb5.conf(5) — go read these next, they're the extended universe 📚

and that's the whole page, bestie!! 🎀 this one shipped with the HEIMDAL source and is dated June 15, 2006 — a vintage classic that still ate, no crumbs left. go get those creds, you're gonna slay 💖✨👑