Wallet...Keytab(3pm)

💖 Wallet::Object::Keytab — the keytab era 💖

okay bestie, so this is Wallet::Object::Keytab, a page from the User Contributed Perl Documentation section (3pm, Perl module vibes). It's the Keytab object implementation for wallet. Kerberos keytabs but make it ✨managed✨. Let's get into it.

---

✨ SYNOPSIS ✨

my @name = qw(keytab host/shell.example.com);
my @trace = ($user, $host, time);
my $object = Wallet::Object::Keytab->create (@name, $schema, @trace);
my $keytab = $object->get (@trace);
$object->destroy (@trace);

like. that's the whole vibe. create, get, destroy. iconic behavior honestly. 💅

---

🌸 DESCRIPTION 🌸

Wallet::Object::Keytab is basically the wallet's representation of Kerberos keytab objects. It implements the wallet object API and provides all the glue you need to create principals in a Kerberos KDC, create and hand back keytabs for those principals, and delete them out of Kerberos when the wallet object gets destroyed. no cap. 🫶

So a keytab is an on-disk store for the key (or keys, plural, she contains multitudes) of a Kerberos principal. Services use keytabs to verify incoming authentication from clients, and automated processes that need to authenticate to Kerberos use them too. To make a keytab you gotta do two things: create the principal in Kerberos, then generate the keytab and store it in a file on disk. two-step process, very demure.

⚠️ this implementation generates a new random key every single time the keytab is retrieved with the get() method — which means it invalidates all existing keytabs. every time. bestie I'm not kidding. all of them.

To use this object, several configuration parameters must be set. Peep Wallet::Config for the deets on those configuration parameters and for info on how to set wallet configuration. go read it, I'll wait. 🎀

---

🦋 METHODS 🦋

This object mostly inherits from Wallet::Object::Base — go read that class's docs for all the generic methods, she's got them all. Down here we're only listing the methods that are overridden or that behave specially for this implementation. special little guys. 💜

---

• attr(ATTRIBUTE [, VALUES, PRINCIPAL, HOSTNAME [, DATETIME]])

Sets or retrieves a given object attribute. The following attribute is supported:

• enctypes

Restricts the generated keytab to a specific set of encryption types. The values of this attribute must be enctype strings recognized by Kerberos (strings like "aes256-cts-hmac-sha1-96" or "des-cbc-crc"). Encryption types must also be present in the list of supported enctypes stored in the database database, or the attr() method will straight-up reject them. 🚫

Also heads up: the salt should not be included, because since the salt is irrelevant for keytab keys, it will always be set to the default by the wallet. so don't even try it.

If this attribute is set, the principal will be restricted to that specific enctype list when get() is called for that keytab. If it's not set, the default set in the KDC will be used. simple as.

💀 This attribute is ignored if the "unchanging" flag is set on a keytab. Keytabs retrieved with "unchanging" set will contain all keys present in the KDC for that Kerberos principal, and therefore may contain different enctypes than those requested by this attribute. so like. don't be surprised.

• sync

This attribute is intended to set a list of external systems with which data about this keytab is synchronized, but there are no supported targets currently. 😭 However! There is support for clearing this attribute or returning its current value. so you can vibe with it, you just can't do anything with it yet. we love an aspirational feature.

If no other arguments besides ATTRIBUTE are given, it returns the values of that attribute, if any, as a list. On error, returns the empty list. To tell the difference between an error and an empty return, call error() afterward. It is guaranteed to return undef unless there was an error.

If other arguments are given, it sets the given ATTRIBUTE values to VALUES, which must be a reference to an array (even if only one value is being set, bestie, yes even then). Pass a reference to an empty array to clear the attribute values. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used. ⏰

• create(TYPE, NAME, DBH, PRINCIPAL, HOSTNAME [, DATETIME])

This is a class method and should be called on the Wallet::Object::Keytab class. It creates a new object with the given TYPE and NAME (TYPE is normally "keytab" and must be, for the rest of the wallet system to use the right class — but this module doesn't check, for ease of subclassing, so like. be cool about it). It uses DBH as the handle to the wallet metadata database. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is creating the object. If DATETIME isn't given, the current time is used. ⏰

When a new keytab object is created, the Kerberos principal designated by NAME is also created in the Kerberos realm determined from the wallet configuration. If the principal already exists, create() still succeeds — which is the whole point, so that a previously unmanaged principal can be imported into the wallet. 🎉 Otherwise, if the Kerberos principal could not be created, create() fails. The principal is created with the randomized keys.

🚨 NAME must not contain the realm. instead, the KEYTAB_REALM configuration variable should be set. See Wallet::Config for more information. do NOT put the realm in the name, I'm serious.

If create() fails, it throws an exception.

• destroy(PRINCIPAL, HOSTNAME [, DATETIME])

Destroys a keytab object by removing it from the database and deleting the principal out of Kerberos. bye bestie 👋 If deleting the principal fails, destroy() fails — but destroy() succeeds if the principal didn't exist when it was called, so that it can be used to clean up stranded entries. very forgiving of you, king. Returns true on success and false on failure. The caller should call error() to get the error message after a failure. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used. ⏰

• get(PRINCIPAL, HOSTNAME [, DATETIME])

Retrieves a keytab for this object and returns the keytab data — or undef on error. The caller should call error() to get the error message if get() returns undef. The keytab is created with new randomized keys, invalidating any existing keytabs for that principal, unless the unchanging flag is set on the object.

😭 say it with me: new randomized keys invalidate every existing keytab for that principal. unless unchanging is set. write it on your mirror.

PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is downloading the keytab. If DATETIME isn't given, the current time is used. ⏰

---

🎀 FILES 🎀

• KEYTAB_TMP/keytab.<pid>

The keytab is created in this file and then read into memory. KEYTAB_TMP is set in the wallet configuration, and <pid> is the process ID of the current process. The file is unlinked after being read. clean up after yourself, we love to see it. ✨

---

💅 LIMITATIONS 💅

Only one Kerberos realm is supported for a given wallet implementation, and all keytab objects stored must be in that realm. Keytab names in the wallet database do not have realm information. one realm. that's the rule. 🫡

---

🌈 SEE ALSO 🌈

kadmin(8), Wallet::Config(3), Wallet::Object::Base(3), wallet-backend(8)

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

---

👑 AUTHOR 👑

Russ Allbery <eagle@eyrie.org>

---

and that's the whole page, bestie!! 🦋 this was Wallet...Keytab(3pm) from the User Contributed Perl Documentation, built with perl v5.40.0 and dated 2024-11-12. go forth and manage your keytabs responsibly, mwah 💖✨🎀