File::...Cipher(3pm)

💖 NAME 💖

File::KDBX::Cipher — a block cipher mode or cipher stream, bestie. That's it, that's the whole vibe ✨

So this lil page is from the User Contributed Perl Documentation set, and it's File::...Cipher(3pm) in case you were wondering which page you clicked on 💅

---

🌸 VERSION 🌸

version 0.906 — yes we're on that version, slay 🎀

---

✨ SYNOPSIS ✨

Okay so here's the whole thing in action, look at her go:

use File::KDBX::Cipher;

my $cipher = File::KDBX::Cipher->new(uuid => $uuid, key => $key, iv => $iv);

my $ciphertext = $cipher->encrypt('plaintext');
$ciphertext .= $cipher->encrypt('more plaintext');
$ciphertext .= $cipher->finish;

my $plaintext = $cipher->decrypt('ciphertext');
$plaintext .= $cipher->decrypt('more ciphertext');
$plaintext .= $cipher->finish;

See how you can just keep feeding her data and then finish? Chef's kiss 👑 The way that streaming works is so iconic honestly.

---

🦋 DESCRIPTION 🦋

A cipher is the thing that encrypts and decrypts your KDBX files, periodt. And good news bestie — the File::KDBX distribution already comes with several pre-registered ciphers, ready to go, no setup required, we love a low-effort queen 💖

Here's the whole roster:

• "61AB05A1-9464-41C3-8D74-3A563DF8DD35" — AES128 (legacy, lowkey giving grandma energy)
• "31C1F2E6-BF71-4350-BE58-05216AFC5AFF" — AES256
• "D6038A2B-8B6F-4CB5-A524-339A31DBB59A" — ChaCha20
• "716E1C8A-EE17-4BDC-93AE-A977B882833A" — Salsa20
• "098563FF-DDF7-4F98-8619-8079F6DB897A" — Serpent
• "AD68F29F-576F-4BB9-A36A-D47AF965346C" — Twofish

🚨 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. From that list above, AES256 and ChaCha20 are the well-supported ones. And you should avoid AES128 for new databases, fr fr, don't do it, it's giving backwards compatibility and nothing else 😭

You can also register your own cipher if you're feeling like a main character. Here's a skeleton to copy:

package File::KDBX::Cipher::MyCipher;

use parent 'File::KDBX::Cipher';

File::KDBX::Cipher->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 encrypt { ... }
sub decrypt { ... }
sub finish  { ... }

sub key_size   { ... }
sub iv_size    { ... }
sub block_size { ... }

Not init being optional though — she's allowed to just vibe 🧚

---

🎀 ATTRIBUTES 🎀

💜 uuid

$uuid = $cipher->uuid;

Get the UUID — but only if the cipher was constructed with one. No UUID, no answer, she's not gonna make one up for you 🙈

💜 stream_id

$stream_id = $cipher->stream_id;

Get the stream ID, if the cipher was constructed with one. Same energy as above.

💜 key

$key = $cipher->key;

Get the raw encryption key. The whole secret, the whole point, protect her with your life 🔥

💜 iv

$iv = $cipher->iv;

Get the initialization vector. Yes that's what IV stands for, iykyk ✨

💜 iv_size

$size = $cipher->iv_size;

Get the expected size of the initialization vector, in bytes. Expected, meaning if you bring the wrong size she will simply not be having it 💅

💜 key_size

$size = $cipher->key_size;

Get the size the mode or stream expects the key to be, in bytes.

💜 block_size

$size = $cipher->block_size;

Get the block size, in bytes. Nice and chunky 📦

💜 algorithm

Get the symmetric cipher algorithm. That's the whole description, she's a woman of few words and honestly? Respect 😌

---

🌈 METHODS 🌈

🌟 new

🌟 new_from_uuid

🌟 new_from_stream_id

$cipher = File::KDBX::Cipher->new(uuid => $uuid, key => $key, iv => $iv);
# OR
$cipher = File::KDBX::Cipher->new_from_uuid($uuid, key => $key, iv => $iv);

$cipher = File::KDBX::Cipher->new(stream_id => $id, key => $key);
# OR
$cipher = File::KDBX::Cipher->new_from_stream_id($id, key => $key);

Construct a new File::KDBX::Cipher. ✨

This is a factory method which returns a subclass — so like, you ask for a cipher and she hands you the right kind of cipher, no cap 🫶

🌟 init

$self->init;

Called by "new" to set attributes. You normally shouldn't call this yourself — it's an internal bestie doing internal bestie things. Returns itself to allow method chaining, which is iconic of her honestly 👑

🌟 encrypt

$ciphertext = $cipher->encrypt($plaintext, ...);

Encrypt some data. Lock it up, hide it, keep it safe 🔒

🌟 decrypt

$plaintext = $cipher->decrypt($ciphertext, ...);

Decrypt some data. Unlock it, reveal it, bring it back 💖

🌟 finish

$ciphertext .= $cipher->finish; # if encrypting
$plaintext  .= $cipher->finish; # if decrypting

Finish the stream — the grand finale, the last little bit of output you need to append. Periodt 🎬

🌟 encrypt_finish

$ciphertext = $cipher->encrypt_finish($plaintext, ...);

Encrypt and finish a stream in one call. Two steps, one girl, efficiency queen 💅

🌟 decrypt_finish

$plaintext = $cipher->decrypt_finish($ciphertext, ...);

Decrypt and finish a stream in one call. Same energy, other direction ✨

🌟 register

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

Register a cipher. Registered ciphers can be used to encrypt and decrypt KDBX databases. Here's the important bit bestie: a cipher's UUID must be unique and musn't change. A cipher UUID gets written into each KDBX file, and the associated cipher must be registered with that same UUID in order to decrypt the KDBX file. So if you change it, you lose access to your own stuff 😭 don't do that to yourself.

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

🌟 unregister

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

Unregister a cipher. Once unregistered, she can no longer be used to encrypt and decrypt KDBX databases — until you reregister her (peep "register"). It's giving "we were on a break" 💀

---

🐛 BUGS 🐛

Please report any bugs or feature requests on the bugtracker website <https://github.com/chazmcgarvey/File-KDBX/issues>

And when you do submit a bug or a request, pretty please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature 🙏 That's the whole ask, it makes everyone's life so much easier, thank you bestie 💖

---

👑 AUTHOR 👑

Charles McGarvey <ccm@cpan.org> — thank you for your service, king 🫡

---

💖 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. Free software! We love to see it 🌈

---

And that's the whole page, babe 🌸 this was File::...Cipher(3pm) from the User Contributed Perl Documentation, built with perl v5.40.1, dated 2025-05-04. Go encrypt something cute, mwah 💋✨