KRB5_KRBHST_INIT(3)

💖 KRB5_KRBHST_INIT 💖

okay bestie, so this is a page from the Library Functions Manual (yeah, the KRB5_KRBHST_INIT(3) one) and it's literally all about looking up Kerberos KDC hosts. group chat rules apply, let's get into it 🎀

✨ NAME ✨

krb5_krbhst_init, krb5_krbhst_init_flags, krb5_krbhst_next, krb5_krbhst_next_as_string, krb5_krbhst_reset, krb5_krbhst_free, krb5_krbhst_format_string, krb5_krbhst_get_addrinfo — lookup Kerberos KDC hosts 🔍👑

📚 LIBRARY 📚

Kerberos 5 Library (libkrb5, -lkrb5) — yeah you gotta link it, no cap.

🌸 SYNOPSIS 🌸

#include <krb5.h>

krb5_error_code
krb5_krbhst_init(krb5_context context, const char *realm,
    unsigned int type, krb5_krbhst_handle *handle);

krb5_error_code
krb5_krbhst_init_flags(krb5_context context, const char *realm,
    unsigned int type, int flags, krb5_krbhst_handle *handle);

krb5_error_code
krb5_krbhst_next(krb5_context context, krb5_krbhst_handle handle,
    krb5_krbhst_info **host);

krb5_error_code
krb5_krbhst_next_as_string(krb5_context context,
    krb5_krbhst_handle handle, char *hostname, size_t hostlen);

void
krb5_krbhst_reset(krb5_context context, krb5_krbhst_handle handle);

void
krb5_krbhst_free(krb5_context context, krb5_krbhst_handle handle);

krb5_error_code
krb5_krbhst_format_string(krb5_context context,
    const krb5_krbhst_info *host, char *hostname, size_t hostlen);

krb5_error_code
krb5_krbhst_get_addrinfo(krb5_context context, krb5_krbhst_info *host,
    struct addrinfo **ai);

💅 DESCRIPTION 💅

So these functions are your little tour guides through every single Kerberos host of one specific realm and one specific service. And the service type can be: the KDCs, the administrative servers, the password changing servers, or the servers that do Kerberos 4 ticket conversion. it's giving ✨options✨

First things first, you grab a handle to a particular service by calling krb5_krbhst_init() (or krb5_krbhst_init_flags()) and you pass it the realm you care about plus the type of service you're looking up. That type can be one of these:

• KRB5_KRBHST_KDC
• KRB5_KRBHST_ADMIN
• KRB5_KRBHST_CHANGEPW
• KRB5_KRBHST_KRB524

The handle gets handed back to you, and bestie, you're gonna pass it to all the other functions. it's the main character of this whole operation 🫶

The flag argument to krb5_krbhst_init_flags is literally the same flags that krb5_send_to_kdc_flags() uses. Possible values are:

• KRB5_KRBHST_FLAGS_MASTER — only talk to master (readwrite) KDC 👑
• KRB5_KRBHST_FLAGS_LARGE_MSG — this is a large message, so use transport that can handle that. big vibes need big pipes 📦

Every single time you call krb5_krbhst_next() you get info on a brand new host. That function returns in host a pointer to a struct holding all the deets about the host — protocol, hostname, port, the whole thing:

typedef struct krb5_krbhst_info {
    enum { KRB5_KRBHST_UDP,
           KRB5_KRBHST_TCP,
           KRB5_KRBHST_HTTP } proto;
    unsigned short port;
    struct addrinfo *ai;
    struct krb5_krbhst_info *next;
    char hostname[1];
} krb5_krbhst_info;

And the related function, krb5_krbhst_next_as_string(), gives you that same info but as a URL-like string. cute, right? 🌈

When there are no more hosts, these functions return KRB5_KDC_UNREACH. that's it, that's the end of the list, no more crumbs 😭

Wanna loop through everything again from the top? Call krb5_krbhst_reset() and the next call to krb5_krbhst_next() will hand you the first host again. rewind, bestie ⏪

When you're done with the handle, you should call krb5_krbhst_free(). don't leave it hanging, that's rude 💀

So you've got a krb5_krbhst_info and you wanna actually use it? There are two functions for that:

• krb5_krbhst_format_string() — returns a printable representation of that struct 🖨️
• krb5_krbhst_get_addrinfo() — returns a struct addrinfo that you can then use to communicate with the server mentioned. say hi to the server for me 🫡

🎀 EXAMPLES 🎀

This code right here prints the KDCs of the realm “MY.REALM”. slay:

krb5_krbhst_handle handle;
char host[MAXHOSTNAMELEN];
krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
while(krb5_krbhst_next_as_string(context, handle,
                                 host, sizeof(host)) == 0)
    printf("%s\n", host);
krb5_krbhst_free(context, handle);

👀 SEE ALSO 👀

getaddrinfo(3), krb5_get_krbhst(3), krb5_send_to_kdc_flags(3) — go read these too, iykyk 📖✨

🦋 HISTORY 🦋

These functions first appeared in Heimdal 0.3g. iconic behavior, honestly.

okay that's the whole page bestie!! 💖 this was the Heimdal manual, dated May 10, 2005 — so like, vintage but make it ✨timeless✨. go forth and find your KDCs, no cap, periodt 💅🎀