KRB5_VERIFY_USER(3)

💖 KRB5_VERIFY_USER 💖

okay so bestie, welcome to krb5_verify_user(3) — yeah it lives in the Library Functions Manual (section 3, we love a 3) and it's the whole Heimdal password verifying function family. buckle up, this is lowkey a lot of functions but they all slay together 🎀

🌈 LIBRARY

Kerberos 5 Library (libkrb5, -lkrb5) 🫶

✨ SYNOPSIS ✨

#include <krb5.h>

krb5_error_code
krb5_verify_user(krb5_context context, krb5_principal principal,
    krb5_ccache ccache, const char *password, krb5_boolean secure,
    const char *service);

krb5_error_code
krb5_verify_user_lrealm(krb5_context context, krb5_principal principal,
    krb5_ccache ccache, const char *password, krb5_boolean secure,
    const char *service);

void
krb5_verify_opt_init(krb5_verify_opt *opt);

void
krb5_verify_opt_alloc(krb5_verify_opt **opt);

void
krb5_verify_opt_free(krb5_verify_opt *opt);

void
krb5_verify_opt_set_ccache(krb5_verify_opt *opt, krb5_ccache ccache);

void
krb5_verify_opt_set_keytab(krb5_verify_opt *opt, krb5_keytab keytab);

void
krb5_verify_opt_set_secure(krb5_verify_opt *opt, krb5_boolean secure);

void
krb5_verify_opt_set_service(krb5_verify_opt *opt, const char *service);

void
krb5_verify_opt_set_flags(krb5_verify_opt *opt, unsigned int flags);

krb5_error_code
krb5_verify_user_opt(krb5_context context, krb5_principal principal,
    const char *password, krb5_verify_opt *opt);

💅 DESCRIPTION 💅

krb5_verify_user does exactly what it says on the tin: it verifies the password a user gave you. the principal whose password is getting checked goes in principal. here's the tea though — new tickets get obtained as a side-effect and stored in ccache (and if that's NULL, the default ccache gets used instead 🫶). also krb5_verify_user() will call krb5_cc_initialize() on the ccache you hand it, so heads up: that ccache must only be initialized with krb5_cc_resolve() or krb5_cc_gen_new(). if you don't pass a password in password (like, you gave it as NULL), the user gets prompted for it. and if secure is set, the ticket gets verified against the locally stored service key service — and if you pass that as NULL, it defaults to 'host' 💀 (yes, just literally the string host).

krb5_verify_user_lrealm() is the same vibe, except it ignores the realm inside principal and tries all the local realms (peep krb5.conf(5)). after a successful return, principal gets set to the authenticated realm, slay. but if the call fails? then principal isn't meaningful anymore and you should only free it with krb5_free_principal(3). no reading it, no trusting it, just free it, periodt.

krb5_verify_opt_alloc() and krb5_verify_opt_free() allocate and free a krb5_verify_opt. bestie, you should use the alloc and free functions instead of allocating the structure yourself — because in a future release the structure won't be exported. so like, don't get attached to it 🙈.

krb5_verify_opt_init() resets all of opt back to default values. fresh start energy ✨.

none of the krb5_verify_opt_set functions make a copy of the data structure they're called with 😭 so it's up to the caller to free them after krb5_verify_user_opt() has been called. your memory, your problem, no cap.

🎀 the setters, one by one 🎀

• krb5_verify_opt_set_ccache() — sets the ccache that the user of opt will use. if you don't set it, the default credential cache is used.
• krb5_verify_opt_set_keytab() — sets the keytab that the user of opt will use. if you don't set it, the default keytab is used.
• krb5_verify_opt_set_secure() — if secure is true, the password verification will require that the ticket gets verified against the locally stored service key. if you don't set it, the default value is true.
• krb5_verify_opt_set_service() — sets the service principal that the user of opt will use. if you don't set it, the 'host' service is used.
• krb5_verify_opt_set_flags() — sets the flags that the user of opt will use. if the flag KRB5_VERIFY_LREALMS is used, then principal gets modified exactly the way krb5_verify_user_lrealm() modifies it 👑

🌟 and finally, the main event 🌟

krb5_verify_user_opt() verifies the password supplied by a user. the principal whose password will be verified is specified in principal, and the options for the verification process get passed in through opt. that's it, that's the function, she's simple and she ate 💅

🦋 EXAMPLES 🦋

here's an example program that verifies a password. it uses the 'host/hostname' service principal in krb5.keytab. so cute, so useful:

#include <krb5.h>

int
main(int argc, char **argv)
{
    char *user;
    krb5_error_code error;
    krb5_principal princ;
    krb5_context context;

    if (argc != 2)
        errx(1, "usage: verify_passwd <principal-name>");

    user = argv[1];

    if (krb5_init_context(&context) < 0)
        errx(1, "krb5_init_context");

    if ((error = krb5_parse_name(context, user, &princ)) != 0)
        krb5_err(context, 1, error, "krb5_parse_name");

    error = krb5_verify_user(context, princ, NULL, NULL, TRUE, NULL);
    if (error)
        krb5_err(context, 1, error, "krb5_verify_user");

    return 0;
}

🔥 SEE ALSO 🔥

• krb5_cc_gen_new(3)
• krb5_cc_initialize(3)
• krb5_cc_resolve(3)
• krb5_err(3)
• krb5_free_principal(3)
• krb5_init_context(3)
• krb5_kt_default(3)
• krb5.conf(5)

and that's the whole page bestie, go verify some passwords, stay secure, and remember: free your principals 🫶

this has been HEIMDAL, dated May 1, 2006 — yes it's giving vintage but she still eats 💖✨🎀