File::KDBX::Safe - Keep strings encrypted while in memory

cipher
           $cipher = $safe->cipher;

       Get the File::KDBX::Cipher::Stream protecting a safe.

       Charles McGarvey <ccm@cpan.org>

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

       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.

       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.

perl v5.40.1                                       2025-05-04                              File::KDBX::Safe(3pm)

       This module provides memory protection functionality. It keeps strings encrypted in memory and decrypts
       them as-needed. Encryption and decryption is done using a File::KDBX::Cipher::Stream.

       A safe can protect one or more (possibly many) strings. When a string is added to a safe, it gets added
       to an internal list so it will be decrypted when the entire safe is unlocked.

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

       Create a new safe for storing secret strings encrypted in memory.

       If a cipher is passed, its stream will be reset.

   clear
           $safe = $safe->clear;

       Clear a safe, removing all store contents permanently. Returns itself to allow method chaining.

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

       Add one or more strings to the memory protection stream. Returns itself to allow method chaining.

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

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

       WARNING: The cipher must be the same as was used to originally encrypt the strings. You must add already-
       encrypted strings in the order in which they were original encrypted or they will not decrypt correctly.
       You almost certainly do not want to add both unprotected and protected strings to a safe.

   unlock
           $safe = $safe->unlock;

       Decrypt all the strings. Each stored string is set to its original value, potentially overwriting any
       value that might have been set after locking the string (so you probably should avoid modification to
       strings while locked). The safe is implicitly cleared. Returns itself to allow method chaining.

       This happens automatically when the safe is garbage-collected.

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

       Peek into the safe at a particular string without decrypting the whole safe. A copy of the string is
       returned, and in order to ensure integrity of the memory protection you should erase the copy when you're
       done.

       Returns "undef" if the given $string is not in memory protection.

       File::KDBX::Safe - Keep strings encrypted while in memory

           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

       version 0.906