Wallet...::File(3pm)

💖 NAME 💖

Wallet::Object::File — the file object implementation for wallet, bestie ✨

okay so real quick, this is the Wallet...::File(3pm) page, aka the module docs for Wallet::Object::File, and it's literally just the blueprint for how wallet handles plain file objects. no cap, it's giving useful.

---

🎀 SYNOPSIS 🎀

my @name = qw(file mysql-lsdb)
my @trace = ($user, $host, time);
my $object = Wallet::Object::File->create (@name, $schema, @trace);
unless ($object->store ("the-password\n")) {
    die $object->error, "\n";
}
my $password = $object->get (@trace);
$object->destroy (@trace);

---

🌸 DESCRIPTION 🌸

So Wallet::Object::File is the whole representation of simple file objects inside the wallet 💖 It implements the wallet object API and brings all the glue you need to stash a file on the wallet server, pull it back out later, and delete it once the file object itself gets deleted. and bestie, listen: a file object has to be stored before you can retrieve it with get. no store, no get. that's the vibe check it enforces. 🫶

Also, to even use this object, you have to set the configuration option that says where on the wallet server to store file objects — like, it genuinely won't know where to put your files otherwise. See Wallet::Config for the deets on that config parameter and how to actually set wallet configuration. 💅

---

👑 METHODS 👑

This object mostly inherits from Wallet::Object::Base, so go read that class's docs for all the generic methods, iykyk. Below is only the stuff that's overridden or behaves specially for this implementation. periodt. 💜

💫 destroy(PRINCIPAL, HOSTNAME [, DATETIME])

Destroys a file object by removing it from the database and deleting the corresponding file on the wallet server. Returns true on success and false on failure — and after a failure, the caller should call error() to get the actual error message. 😭

PRINCIPAL, HOSTNAME, and DATETIME get 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 the current contents of the file object, or undef on error. store() must be called before get() will be successful (yes, for real, no skipping steps bestie). The caller should call error() to get the error message if get() returns undef.

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

💫 checksum(PRINCIPAL, HOSTNAME [, DATETIME])

Retrieves the checksum for contents of the file object, or undef on error. PRINCIPAL, HOSTNAME, and DATETIME get stored as history information. PRINCIPAL should be the user who is downloading the keytab. If DATETIME isn't given, the current time is used. 🦋

💫 store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])

Store DATA as the current contents of the file object. Heads up: any existing data will be overwritten — like, gone, replaced, that's the whole deal. Returns true on success and false on failure, and the caller should call error() to get the error message after a failure.

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

fr fr: if FILE_MAX_SIZE is set in the wallet configuration, a store() of DATA larger than that configuration setting will be rejected. so don't try to sneak a huge file past it, it will not slay. 💀

---

🍓 FILES 🍓

FILE_BUCKET/<hash>/<file>

Files are stored on the wallet server under the directory FILE_BUCKET, as set in the wallet configuration. 🌈

• <hash> is the first two characters of the hex-encoded MD5 hash of the wallet file object name — this exists so we don't cram way too many files into the same directory, iconic crowd control honestly.
• <file> is the name of the file object with all characters other than alphanumerics, underscores, and dashes replaced by "%" and the hex code of the character. 🎀

---

🧚 LIMITATIONS 🧚

The wallet implementation itself can handle arbitrary file object names — flexible queen. However, due to limitations in the remctld server usually used to run wallet-backend, file object names containing nul characters (ASCII 0) may not be permitted. 🙈

And the file system used for storing file objects may impose a length limitation on the file object name. so like, keep those names cute and short-ish, bestie.

---

⭐ SEE ALSO ⭐

remctld(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/>. 💖

---

💜 AUTHORS 💜

Russ Allbery <eagle@eyrie.org> and Bill MacAllister <bill@ca-zephyr.org> — the actual legends who wrote this. bow down. 👑

---

and that's the whole page, bestie 💅 this was perl v5.40.0, dated 2024-11-12, and it's the Wallet...::File(3pm) manual — go forth and store your files responsibly 🫶✨