File::KDBX::Safe(3pm)

💖 File::KDBX::Safe 💖

okay bestie, so this is a page from the User Contributed Perl Documentation set — that's the posh name for the perldoc manual File::KDBX::Safe(3pm). It lives on your system as a perl manpage, and I'm about to make it make sense.

---

✨ NAME ✨

File::KDBX::Safe — keeps your strings encrypted while they're just vibing in memory. 🔐

---

🌸 VERSION 🌸

This is version 0.906, bestie. Noted. Periodt.

---

🦋 SYNOPSIS 🦋

use File::KDBX::Safe;

$safe = File::KDBX::Safe->new;

my $msg = 'Secret text';
$safe->add(\$msg);
# $msg is now undef, the original message no longer in RAM

my $obj = { value => 'Also secret' };
$safe->add($obj);
# $obj is now { value => undef }

say $safe->peek($msg);  # Secret text

$safe->unlock;
say $msg;               # Secret text
say $obj->{value};      # Also secret

like… look at her go. 🫶

---

👑 DESCRIPTION 👑

This module is all about memory protection, and no cap, that's the whole point. It keeps strings encrypted while they're sitting in memory and only decrypts them on an as-needed basis. The encryption and decryption heavy lifting is done by a File::KDBX::Cipher::Stream. 💅

One safe can protect one string, or a bunch of them — like, seriously, as many as you want. When you add a string to a safe, it gets tossed onto an internal list, and that list is the thing that gets decrypted when you unlock the whole entire safe. it's giving ✨organized✨.

---

🎀 ATTRIBUTES 🎀

💜 cipher

$cipher = $safe->cipher;

Get the File::KDBX::Cipher::Stream that's protecting a safe. that's it, that's the whole attribute. iconic.

---

🔥 METHODS 🔥

⭐ new

$safe = File::KDBX::Safe->new(%attributes);
$safe = File::KDBX::Safe->new(\@strings, %attributes);

Make yourself a brand new safe for storing secret strings encrypted in memory. 🧚

If you pass a cipher in, its stream will be reset. just so you know.

💖 clear

$safe = $safe->clear;

Clear out a safe — removes all the store contents, and it's permanent, bestie, no take-backs. 😭

It returns itself so you can chain methods like the main character you are.

💀 lock

💀 add

$safe = $safe->lock(@strings);
$safe = $safe->lock(\@strings);

Add one or more strings to the memory protection stream. Returns itself, chaining enabled, slay. 🎀

🙈 lock_protected

🙈 add_protected

$safe = $safe->lock_protected(@strings);
$safe = $safe->lock_protected(\@strings);

Add strings that are already encrypted. Returns itself to allow method chaining, obviously.

⚠️ WARNING, and I mean it: the cipher has to be the same one that was used to originally encrypt those strings. And you must add already-encrypted strings in the exact order in which they were originally encrypted, or they will not decrypt correctly. no shade, it just will not work. Also — you almost certainly do not want to add both unprotected and protected strings to the same safe. pick a lane bestie. 🫠

🌈 unlock

$safe = $safe->unlock;

Decrypt all the strings. Each stored string gets set back to its original value, which could potentially overwrite whatever value got set after you locked the string — so yeah, you probably should avoid modifying strings while they're locked. 🙈

The safe is implicitly cleared. Returns itself to allow method chaining.

fun fact: this happens automatically when the safe gets garbage-collected. the safe cleans up after herself, as she should. ✨

🍓 peek

$string_value = $safe->peek($string);
...
erase $string_value;

Peek into the safe at one particular string without decrypting the whole entire safe. You get back a copy of the string, and to keep the integrity of your memory protection intact, you should erase that copy when you're done with it. don't leave it lying around. 💅

Returns undef if the $string you gave it isn't in memory protection.

---

💀 BUGS 💀

Found a bug? Want a feature? Please report it on the bugtracker website:

https://github.com/chazmcgarvey/File-KDBX/issues

And when you submit that bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature. receipts, bestie, we need receipts. 🫶

---

👑 AUTHOR 👑

Charles McGarvey <ccm@cpan.org> — the icon behind all this. 💖

---

📜 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.

---

aaaand that's the whole page! 🎉 this was perl v5.40.1, dated 2025-05-04, from the File::KDBX::Safe(3pm) manual. go forth and keep your secrets encrypted, bestie. 🦋💜✨