KRB5-PLUGIN(7)

✨ krb5-plugin — bestie's guide to the Heimdal plugin interface ✨

okay so real talk: this is krb5-plugin(7), a page from the Miscellaneous Information Manual, and it's all about how plugins work in Heimdal. if you've ever wanted to bolt your own lil brain onto Heimdal without touching the source, this is your moment. 💅

---

🌸 SYNOPSIS 🌸

#include <krb5.h>
#include <krb5/an2ln_plugin.h>
#include <krb5/ccache_plugin.h>
#include <krb5/db_plugin.h>
#include <krb5/kuserok_plugin.h>
#include <krb5/locate_plugin.h>
#include <krb5/send_to_kdc_plugin.h>

like, include the ones you need, bestie. they're all right there. 🎀

---

💖 DESCRIPTION 💖

Heimdal has a plugin interface, and it's giving ✨extensible✨. Plugins can go two ways:

• they can be statically linked into Heimdal and registered via the krb5_plugin_register(3) function, or
• they can be dynamically loaded from shared objects hanging out in the Heimdal plugins directories.

Plugins are literally just a C struct. the struct name is given in the associated header file — for example, krb5plugin_kuserok_ftable — and a pointer to it is either:

• registered via krb5_plugin_register(3), or
• found in a shared object via a symbol lookup for the symbol name defined in the associated header file (e.g., "kuserok" for the plugin for krb5_kuserok(3)).

no cap, that's the whole mechanism. 🦋

---

🌈 the three common fields (the iconic trio) 🌈

the plugin structs for all plugin types always begin with the same three common fields:

1. minor_version, an int. plugin minor versions are defined in each plugin type's associated header file.
2. init, a pointer to a function with two arguments — a krb5_context and a void ** — returning a krb5_error_code. this function will be called to initialize a plugin-specific context in the form of a void * that will be output through the init function's second argument.
3. fini, a pointer to a function of one argument, a void *, consisting of the plugin's context to be destroyed, and returning void.

---

👑 the rules of engagement 👑

each plugin type must add zero or more fields to this struct following the above three. so the first three are non-negotiable, the rest is your canvas, bestie.

Plugins are typically invoked in no particular order until one succeeds or fails, or all return a special return value such as KRB5_PLUGIN_NO_HANDLE to indicate that the plugin was not applicable. (yes, chaos order, we love that for us 😭)

Most plugin types obtain deterministic plugin behavior in spite of the non-deterministic invocation order by, for example, invoking all plugins for each "rule" and passing the rule to each plugin with the expectation that just one plugin will match any given rule. so like... the order is random but the outcome is consistent. main character energy. 💅

---

🗄️ the database plugin system 🗄️

There is a database plugin system intended for many of the uses of databases in Heimdal. The plugin is expected to call heim_db_register(3) from its init entry point to register a DB type. The DB plugin's fini function must do nothing, and the plugin must not provide any other entry points.

okay that's a hard rule, not a suggestion. fini does nothing, no extra entry points, periodt. 🙈

---

🫶 the krb5_kuserok plugin 🫶

The krb5_kuserok plugin adds a single field to its struct: a pointer to a function that implements kuserok functionality with the following form:

static krb5_error_code
kuserok(void *plug_ctx, krb5_context context, const char *rule,
        unsigned int flags, const char *k5login_dir,
        const char *luser, krb5_const_principal principal,
        krb5_boolean *result)

The luser, principal and result arguments are self-explanatory (see krb5_kuserok(3)). The plug_ctx argument is the context output by the plugin's init function. The rule argument is a kuserok rule from the krb5.conf file; each plugin is invoked once for each rule until all plugins fail or one succeeds. The k5login_dir argument provides an alternative k5login file location, if not NULL. The flags argument indicates whether the plugin may call krb5_aname_to_localname(3) (KUSEROK_ANAME_TO_LNAME_OK), and whether k5login databases are expected to be authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE).

---

🧚 the an2ln plugin 🧚

The plugin for krb5_aname_to_localname(3) is named "an2ln" and has a single extra field for the plugin struct:

typedef krb5_error_code (*set_result_f)(void *, const char *);

static krb5_error_code
an2ln(void *plug_ctx, krb5_context context, const char *rule,
      krb5_const_principal aname, set_result_f set_res_f, void *set_res_ctx)

The arguments for the an2ln plugin are similar to those of the kuserok plugin, but the result, being a string, is set by calling the set_res_f function argument with the set_res_ctx and result string as arguments. The set_res_f function will make a copy of the string.

so like, you don't hand it a string pointer and pray — it copies. obsessed. 🍓

---

🎀 FILES 🎀

• libdir/plugin/krb5/* — Shared objects containing plugins for Heimdal.

that's where your lil shared objects live, bestie. 💖

---

⭐ EXAMPLES ⭐

🌸 example 1: an an2ln plugin that maps principals to a constant "nouser" 🌸

An example an2ln plugin that maps principals to a constant "nouser" follows:

#include <krb5/an2ln_plugin.h>

static krb5_error_code KRB5_CALLCONV
nouser_plug_init(krb5_context context, void **ctx)
{
    *ctx = NULL;
    return 0;
}

static void KRB5_CALLCONV nouser_plug_fini(void *ctx) { }

static krb5_error_code KRB5_CALLCONV
nouser_plug_an2ln(void *plug_ctx, krb5_context context,
                  const char *rule,
                  krb5_const_principal aname,
                  set_result_f set_res_f, void *set_res_ctx)
{
    krb5_error_code ret;

    if (strcmp(rule, "NOUSER") != 0)
        return KRB5_PLUGIN_NO_HANDLE;

    ret = set_res_f(set_res_ctx, "nouser");

    return ret;
}

krb5plugin_an2ln_ftable an2ln = {
    KRB5_PLUGIN_AN2LN_VERSION_0,
    nouser_plug_init,
    nouser_plug_fini,
    nouser_plug_an2ln,
};

look at that KRB5_PLUGIN_NO_HANDLE bailing when the rule isn't "NOUSER" — that's the polite way of saying "not my problem bestie" 😌

---

💜 example 2: a kuserok plugin that rejects all requests 💜

An example kuserok plugin that rejects all requests follows. (Note that there exists a built-in plugin with this functionality; see krb5_kuserok(3)).

#include <krb5/kuserok_plugin.h>

static krb5_error_code KRB5_CALLCONV
reject_plug_init(krb5_context context, void **ctx)
{
    *ctx = NULL;
    return 0;
}

static void KRB5_CALLCONV reject_plug_fini(void *ctx) { }

static krb5_error_code KRB5_CALLCONV
reject_plug_kuserok(void *plug_ctx, krb5_context context, const char *rule,
                    unsigned int flags, const char *k5login_dir,
                    const char *luser, krb5_const_principal principal,
                    krb5_boolean *result)
{
    if (strcmp(rule, "REJECT") != 0)
        return KRB5_PLUGIN_NO_HANDLE;

    *result = FALSE;
    return 0;
}

krb5plugin_kuserok_ftable kuserok = {
    KRB5_PLUGIN_KUSEROK_VERSION_0,
    reject_plug_init,
    reject_plug_fini,
    reject_plug_kuserok,
};

a plugin whose entire personality is saying no. honestly? iconic. 🚫✨

---

👀 SEE ALSO 👀

• krb5_plugin_register(3)
• krb5_kuserok(3)
• krb5_aname_to_localname(3)

go read those, iykyk. 📚

---

and that's the whole page bestie!! this was HEIMDAL, dated December 21, 2011 — yeah she's an elder but she's still serving 💖 now go write a plugin and make it slay. 🦋✨