File::KDBX::KDF(3pm)

💖 File::KDBX::KDF — a key derivation function 💖

okay bestie, welcome to File::KDBX::KDF, part of the File::KDBX distribution, documented in the User Contributed Perl Documentation section of the manual. this is where keys get transformed, and it's lowkey the most important glow-up in the whole KDBX pipeline. 🦋

version 0.906

---

✨ DESCRIPTION ✨

so. a KDF (that's key derivation function, keep up 💅) is what you use in the transformation of a master key — like, one or more component keys all smooshed together — to produce the actual final encryption key that protects a KDBX database. it's giving ✨ cryptographic makeover ✨.

the File::KDBX distribution already comes with several pre-registered KDFs ready to go, no setup needed:

• "C9D9F39A-628A-4460-BF74-0D08C18A4FEA" — AES
• "7C02BB82-79A7-4AC0-927D-114A00648238" — AES (challenge-response variant)
• "EF636DDF-8C29-444B-91F7-A9A403E30A0C" — Argon2d
• "9E298B19-56DB-4773-B23D-FC3EC6F0A1E6" — Argon2id

NOTE: if you want your KDBX file to actually be readable by other KeePass implementations, you must use a UUID and algorithm that they support. out of the list above, all of them are well-supported except the AES challenge-response variant, which is kind of a pseudo KDF and isn't usually written into files. all of these are good though fr fr. AES has a longer track record, but Argon2 has better ASIC resistance. 🫶

and guess what — you can also "register" your own KDF. main character energy. here's a skeleton:

package File::KDBX::KDF::MyKDF;

use parent 'File::KDBX::KDF';

File::KDBX::KDF->register(
    # $uuid, $package, %args
    "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
);

sub init { ... } # optional

sub _transform { my ($key) = @_; ... }

---

🎀 ATTRIBUTES 🎀

uuid

$uuid => $kdf->uuid;

get the UUID that's used to figure out which function to use. it's the name tag of the KDF world. 👑

seed

$seed = $kdf->seed;

get the seed — or the salt, depending on which function you're running. same vibe, different label. 🧂

---

🌸 METHODS 🌸

new

$kdf = File::KDBX::KDF->new(parameters => \%params);

construct a brand new KDF. fresh out the box. ✨

init

$kdf = $kdf->init(%attributes);

called by new to set attributes. you normally shouldn't call this yourself — it's giving backstage crew, not cast member. 🙈 returns itself so you can chain methods, which is iconic.

transform

$transformed_key = $kdf->transform($key);
$transformed_key = $kdf->transform($key, $challenge);

transform a key. the input key can be either a File::KDBX::Key or a raw binary key, and the transformed key you get back will be a raw key.

heads up: this can take awhile, depending on the KDF parameters. like, go make a snack. 😭

if a challenge is provided (and the KDF is AES except for the KeePassXC variant), it will be passed to the key so challenge-response keys can produce raw keys. see "raw_key" in File::KDBX::Key. iykyk. 💅

randomize_seed

$kdf->randomize_seed;

generate and set a new random seed/salt. chaos, but make it cryptographic. 🎲

register

File::KDBX::KDF->register($uuid => $package, %args);

register a KDF. registered KDFs can be used to encrypt and decrypt KDBX databases. a KDF's UUID must be unique and musn't change — like, ever, periodt. a KDF UUID is written into each KDBX file, and the associated KDF must be registered with the same UUID in order to decrypt that KDBX file.

$package should be a Perl package relative to "File::KDBX::KDF::", or prefixed with a "+" if it's a fully-qualified package. %args get passed as-is to the KDF's init method.

unregister

File::KDBX::KDF->unregister($uuid);

unregister a KDF. unregistered KDFs can no longer be used to encrypt and decrypt KDBX databases — until you reregister them (see "register"). it's giving "blocked but the block is reversible". 🙈

---

💀 BUGS 💀

please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/File-KDBX/issues — they want to hear from you bestie, fr fr.

when submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. receipts matter. 🧾✨

---

👑 AUTHOR 👑

Charles McGarvey <ccm@cpan.org>

---

💜 COPYRIGHT AND LICENSE 💜

this software is copyright (c) 2022 by Charles McGarvey.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay that's the whole page! 🫶 this was rendered by perl v5.40.1 on 2025-05-04, and it lives under File::KDBX::KDF(3pm). now go transform some keys, slay, and don't forget to register your UUID correctly — no cap. 💖✨🎀🦋🌸💅