1File::KDBX::Safe(3)   User Contributed Perl Documentation  File::KDBX::Safe(3)
2
3
4

NAME

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

VERSION

9       version 0.906
10

SYNOPSIS

12           use File::KDBX::Safe;
13
14           $safe = File::KDBX::Safe->new;
15
16           my $msg = 'Secret text';
17           $safe->add(\$msg);
18           # $msg is now undef, the original message no longer in RAM
19
20           my $obj = { value => 'Also secret' };
21           $safe->add($obj);
22           # $obj is now { value => undef }
23
24           say $safe->peek($msg);  # Secret text
25
26           $safe->unlock;
27           say $msg;               # Secret text
28           say $obj->{value};      # Also secret
29

DESCRIPTION

31       This module provides memory protection functionality. It keeps strings
32       encrypted in memory and decrypts them as-needed. Encryption and
33       decryption is done using a File::KDBX::Cipher::Stream.
34
35       A safe can protect one or more (possibly many) strings. When a string
36       is added to a safe, it gets added to an internal list so it will be
37       decrypted when the entire safe is unlocked.
38

ATTRIBUTES

40   cipher
41           $cipher = $safe->cipher;
42
43       Get the File::KDBX::Cipher::Stream protecting a safe.
44

METHODS

46   new
47           $safe = File::KDBX::Safe->new(%attributes);
48           $safe = File::KDBX::Safe->new(\@strings, %attributes);
49
50       Create a new safe for storing secret strings encrypted in memory.
51
52       If a cipher is passed, its stream will be reset.
53
54   clear
55           $safe = $safe->clear;
56
57       Clear a safe, removing all store contents permanently. Returns itself
58       to allow method chaining.
59
60   lock
61   add
62           $safe = $safe->lock(@strings);
63           $safe = $safe->lock(\@strings);
64
65       Add one or more strings to the memory protection stream. Returns itself
66       to allow method chaining.
67
68   lock_protected
69   add_protected
70           $safe = $safe->lock_protected(@strings);
71           $safe = $safe->lock_protected(\@strings);
72
73       Add strings that are already encrypted. Returns itself to allow method
74       chaining.
75
76       WARNING: The cipher must be the same as was used to originally encrypt
77       the strings. You must add already-encrypted strings in the order in
78       which they were original encrypted or they will not decrypt correctly.
79       You almost certainly do not want to add both unprotected and protected
80       strings to a safe.
81
82   unlock
83           $safe = $safe->unlock;
84
85       Decrypt all the strings. Each stored string is set to its original
86       value, potentially overwriting any value that might have been set after
87       locking the string (so you probably should avoid modification to
88       strings while locked). The safe is implicitly cleared. Returns itself
89       to allow method chaining.
90
91       This happens automatically when the safe is garbage-collected.
92
93   peek
94           $string_value = $safe->peek($string);
95           ...
96           erase $string_value;
97
98       Peek into the safe at a particular string without decrypting the whole
99       safe. A copy of the string is returned, and in order to ensure
100       integrity of the memory protection you should erase the copy when
101       you're done.
102
103       Returns "undef" if the given $string is not in memory protection.
104

BUGS

106       Please report any bugs or feature requests on the bugtracker website
107       <https://github.com/chazmcgarvey/File-KDBX/issues>
108
109       When submitting a bug or request, please include a test-file or a patch
110       to an existing test-file that illustrates the bug or desired feature.
111

AUTHOR

113       Charles McGarvey <ccm@cpan.org>
114

116       This software is copyright (c) 2022 by Charles McGarvey.
117
118       This is free software; you can redistribute it and/or modify it under
119       the same terms as the Perl 5 programming language system itself.
120
121
122
123perl v5.38.0                      2023-09-27               File::KDBX::Safe(3)
Impressum