Wallet::Kadmin(3pm)

📦 version 1.7, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Wallet::Kadmin 💖

okay so bestie, you're looking at the User Contributed Perl Documentation for Wallet::Kadmin, and trust me, it's giving very much "the backbone of your keytab dreams." ✨ Let's get into it.

🌸 NAME 🌸

Wallet::Kadmin — the Kerberos administration API for the wallet keytab backend. 💅

✨ SYNOPSIS ✨

my $kadmin = Wallet::Kadmin->new;
$kadmin->create ('host/foo.example.com');
my $data = $kadmin->keytab_rekey ('host/foo.example.com',
                                  'aes256-cts-hmac-sha1-96');
$data = $kadmin->keytab ('host/foo.example.com');
my $exists = $kadmin->exists ('host/oldshell.example.com');
$kadmin->destroy ('host/oldshell.example.com') if $exists;

like… look at her. so clean. so powerful. 🫶

🦋 DESCRIPTION 🦋

So Wallet::Kadmin is a wrapper and a base class for modules that give wallet an interface to do Kerberos administration — specifically, to create and delete principals and to create keytabs for a principal. 🎀

Each subclass is out here administering a specific type of Kerberos implementation — think MIT Kerberos or Heimdal — and it provides a standard set of API calls you use to interact with that implementation's kadmin interface. one API to rule them all, no cap. 👑

The class hits up Wallet::Config to find out which type of kadmin interface is in use, and then hands you back an object to use for interacting with that interface. Wanna know how to set it up? Peep "KEYTAB OBJECT CONFIGURATION" in Wallet::Config for all the deets. 📝

👑 CLASS METHODS 👑

new()

Finds the proper Kerberos implementation and calls the new() constructor for that implementation's module, then returns the resulting object. If the implementation isn't recognized or isn't set? It dies with an error message. periodt. 💀

💜 INSTANCE METHODS 💜

These methods are provided by any object that new() returns, no matter which underlying kadmin interface you've got going on. They're implemented by the child class that's appropriate for whatever Kerberos implementation is configured. 🧚

create(PRINCIPAL)

Adds a new principal with a given name. The principal gets created with a random password, plus any other flags set by Wallet::Config. Returns true on success and false on failure. And if the principal already exists? It returns true anyway — because bestie, we are simply bringing our expectations in line with reality. 🌈

destroy(PRINCIPAL)

Removes a principal with the given name. Returns true on success or false on failure. If the principal doesn't exist, it returns true — again, bringing our expectations in line with reality. iconic behavior honestly. ✨

error([ERROR ...])

Returns the error of the last failing operation, or undef if no operations have failed. Callers should call this function to grab the error message after any other instance method hands back an undef. 👀

For the convenience of child classes, this method can also be called with one or more error strings. If you do that, those strings get concatenated together, trailing newlines get removed, any text of the form at \S+ line \d+\.? at the end of the message gets stripped off, and the result is stored as the error. ⚠️ Only child classes should call this method with an error string, okay?

exists(PRINCIPAL)

Returns true if the given principal exists in the KDC and 0 if it doesn't. And if an error gets encountered while checking whether the principal exists, exists() returns undef. 🙈

fork_callback(CALLBACK)

If the module has to fork an external process for some reason — like, say, a kadmin command-line client — then the sub CALLBACK will be called in the child process before running the program. This is handy for, for example, properly cleaning up shared database handles. 🧹

keytab(PRINCIPAL)

keytab() creates a keytab for the given principal and stores it in the given file. A keytab is an on-disk store for the key or keys for a Kerberos principal. Keytabs get used by services to verify incoming authentication from clients, or by automated processes that need to authenticate to Kerberos. 🔐

Heads up bestie: to create a keytab, the principal has to have previously been created in the Kerberos KDC. No skipping steps! 💅

Returns the keytab as binary data on success and undef on failure.

keytab_rekey(PRINCIPAL [, ENCTYPE ...])

Like keytab(), but it randomizes the key for the principal before generating the keytab and writes it to the given file. ⚠️ This will invalidate any existing keytabs for that principal, so like… be aware. 😭

This method can also limit the encryption types of the keys for that principal via the optional ENCTYPE arguments. The enctype values must be enctype strings recognized by the Kerberos implementation — strings like "aes256-cts-hmac-sha1-96" or "des-cbc-crc". If none are given, the KDC defaults will be used. Returns the keytab as binary data on success and undef on failure. 🔥

the utility squad 🛠️

The following methods are utility methods to aid with child class implementation, and they should only be called by child classes. don't be out here calling them yourself, iykyk.

read_keytab(FILE)

Reads the contents of the keytab stored in FILE into memory and returns it as binary data. On failure, returns undef and sets the object error. 🍓

🌟 SEE ALSO 🌟

This module is part of the wallet system. The current version is available from <https://www.eyrie.org/~eagle/software/wallet/>. ⭐

🎀 AUTHORS 🎀

Jon Robertson <jonrober@stanford.edu> and Russ Allbery <eagle@eyrie.org> — absolute legends, we thank them for their service. 🫶

and that's the whole vibe, bestie 💖 this page came to you courtesy of perl v5.40.0, dated 2024-11-12, and it's the Wallet::Kadmin(3pm) manual — go forth and administer those principals, you've got this. slay. 💅✨

📦 where this page comes from