]> Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX.pm
4768eefa4108a056c40cce46e1d57bc8163f2994
[chaz/p5-File-KDBX] / lib / File / KDBX.pm
1 package File::KDBX;
2 # ABSTRACT: Encrypted database to store secret text and files
3
4 use warnings;
5 use strict;
6
7 use Crypt::Digest qw(digest_data);
8 use Crypt::PRNG qw(random_bytes);
9 use Devel::GlobalDestruction;
10 use File::KDBX::Constants qw(:all :icon);
11 use File::KDBX::Error;
12 use File::KDBX::Safe;
13 use File::KDBX::Util qw(:class :coercion :empty :search :uuid erase simple_expression_query snakify);
14 use Hash::Util::FieldHash qw(fieldhashes);
15 use List::Util qw(any first);
16 use Ref::Util qw(is_ref is_arrayref is_plain_hashref);
17 use Scalar::Util qw(blessed);
18 use Time::Piece;
19 use boolean;
20 use namespace::clean;
21
22 our $VERSION = '999.999'; # VERSION
23 our $WARNINGS = 1;
24
25 fieldhashes \my (%SAFE, %KEYS);
26
27 =method new
28
29 $kdbx = File::KDBX->new(%attributes);
30 $kdbx = File::KDBX->new($kdbx); # copy constructor
31
32 Construct a new L<File::KDBX>.
33
34 =cut
35
36 sub new {
37 my $class = shift;
38
39 # copy constructor
40 return $_[0]->clone if @_ == 1 && blessed $_[0] && $_[0]->isa($class);
41
42 my $self = bless {}, $class;
43 $self->init(@_);
44 $self->_set_nonlazy_attributes if empty $self;
45 return $self;
46 }
47
48 sub DESTROY { local ($., $@, $!, $^E, $?); !in_global_destruction and $_[0]->reset }
49
50 =method init
51
52 $kdbx = $kdbx->init(%attributes);
53
54 Initialize a L<File::KDBX> with a set of attributes. Returns itself to allow method chaining.
55
56 This is called by L</new>.
57
58 =cut
59
60 sub init {
61 my $self = shift;
62 my %args = @_;
63
64 @$self{keys %args} = values %args;
65
66 return $self;
67 }
68
69 =method reset
70
71 $kdbx = $kdbx->reset;
72
73 Set a L<File::KDBX> to an empty state, ready to load a KDBX file or build a new one. Returns itself to allow
74 method chaining.
75
76 =cut
77
78 sub reset {
79 my $self = shift;
80 erase $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY};
81 erase $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY};
82 erase $self->{raw};
83 %$self = ();
84 $self->_remove_safe;
85 return $self;
86 }
87
88 =method clone
89
90 $kdbx_copy = $kdbx->clone;
91 $kdbx_copy = File::KDBX->new($kdbx);
92
93 Clone a L<File::KDBX>. The clone will be an exact copy and completely independent of the original.
94
95 =cut
96
97 sub clone {
98 my $self = shift;
99 require Storable;
100 return Storable::dclone($self);
101 }
102
103 sub STORABLE_freeze {
104 my $self = shift;
105 my $cloning = shift;
106
107 my $copy = {%$self};
108
109 return '', $copy, $KEYS{$self} // (), $SAFE{$self} // ();
110 }
111
112 sub STORABLE_thaw {
113 my $self = shift;
114 my $cloning = shift;
115 shift;
116 my $clone = shift;
117 my $key = shift;
118 my $safe = shift;
119
120 @$self{keys %$clone} = values %$clone;
121 $KEYS{$self} = $key;
122 $SAFE{$self} = $safe;
123
124 # Dualvars aren't cloned as dualvars, so coerce the compression flags.
125 $self->compression_flags($self->compression_flags);
126
127 $self->objects(history => 1)->each(sub { $_->kdbx($self) });
128 }
129
130 ##############################################################################
131
132 =method load
133
134 =method load_string
135
136 =method load_file
137
138 =method load_handle
139
140 $kdbx = KDBX::File->load(\$string, $key);
141 $kdbx = KDBX::File->load(*IO, $key);
142 $kdbx = KDBX::File->load($filepath, $key);
143 $kdbx->load(...); # also instance method
144
145 $kdbx = File::KDBX->load_string($string, $key);
146 $kdbx = File::KDBX->load_string(\$string, $key);
147 $kdbx->load_string(...); # also instance method
148
149 $kdbx = File::KDBX->load_file($filepath, $key);
150 $kdbx->load_file(...); # also instance method
151
152 $kdbx = File::KDBX->load_handle($fh, $key);
153 $kdbx = File::KDBX->load_handle(*IO, $key);
154 $kdbx->load_handle(...); # also instance method
155
156 Load a KDBX file from a string buffer, IO handle or file from a filesystem.
157
158 L<File::KDBX::Loader> does the heavy lifting.
159
160 =cut
161
162 sub load { shift->_loader->load(@_) }
163 sub load_string { shift->_loader->load_string(@_) }
164 sub load_file { shift->_loader->load_file(@_) }
165 sub load_handle { shift->_loader->load_handle(@_) }
166
167 sub _loader {
168 my $self = shift;
169 $self = $self->new if !ref $self;
170 require File::KDBX::Loader;
171 File::KDBX::Loader->new(kdbx => $self);
172 }
173
174 =method dump
175
176 =method dump_string
177
178 =method dump_file
179
180 =method dump_handle
181
182 $kdbx->dump(\$string, $key);
183 $kdbx->dump(*IO, $key);
184 $kdbx->dump($filepath, $key);
185
186 $kdbx->dump_string(\$string, $key);
187 \$string = $kdbx->dump_string($key);
188
189 $kdbx->dump_file($filepath, $key);
190
191 $kdbx->dump_handle($fh, $key);
192 $kdbx->dump_handle(*IO, $key);
193
194 Dump a KDBX file to a string buffer, IO handle or file in a filesystem.
195
196 L<File::KDBX::Dumper> does the heavy lifting.
197
198 =cut
199
200 sub dump { shift->_dumper->dump(@_) }
201 sub dump_string { shift->_dumper->dump_string(@_) }
202 sub dump_file { shift->_dumper->dump_file(@_) }
203 sub dump_handle { shift->_dumper->dump_handle(@_) }
204
205 sub _dumper {
206 my $self = shift;
207 $self = $self->new if !ref $self;
208 require File::KDBX::Dumper;
209 File::KDBX::Dumper->new(kdbx => $self);
210 }
211
212 ##############################################################################
213
214 =method user_agent_string
215
216 $string = $kdbx->user_agent_string;
217
218 Get a text string identifying the database client software.
219
220 =cut
221
222 sub user_agent_string {
223 require Config;
224 sprintf('%s/%s (%s/%s; %s/%s; %s)',
225 __PACKAGE__, $VERSION, @Config::Config{qw(package version osname osvers archname)});
226 }
227
228 has sig1 => KDBX_SIG1, coerce => \&to_number;
229 has sig2 => KDBX_SIG2_2, coerce => \&to_number;
230 has version => KDBX_VERSION_3_1, coerce => \&to_number;
231 has headers => {};
232 has inner_headers => {};
233 has meta => {};
234 has binaries => {};
235 has deleted_objects => {};
236 has raw => coerce => \&to_string;
237
238 # HEADERS
239 has 'headers.comment' => '', coerce => \&to_string;
240 has 'headers.cipher_id' => CIPHER_UUID_CHACHA20, coerce => \&to_uuid;
241 has 'headers.compression_flags' => COMPRESSION_GZIP, coerce => \&to_compression_constant;
242 has 'headers.master_seed' => sub { random_bytes(32) }, coerce => \&to_string;
243 has 'headers.encryption_iv' => sub { random_bytes(16) }, coerce => \&to_string;
244 has 'headers.stream_start_bytes' => sub { random_bytes(32) }, coerce => \&to_string;
245 has 'headers.kdf_parameters' => sub {
246 +{
247 KDF_PARAM_UUID() => KDF_UUID_AES,
248 KDF_PARAM_AES_ROUNDS() => $_[0]->headers->{+HEADER_TRANSFORM_ROUNDS} // KDF_DEFAULT_AES_ROUNDS,
249 KDF_PARAM_AES_SEED() => $_[0]->headers->{+HEADER_TRANSFORM_SEED} // random_bytes(32),
250 };
251 };
252 # has 'headers.transform_seed' => sub { random_bytes(32) };
253 # has 'headers.transform_rounds' => 100_000;
254 # has 'headers.inner_random_stream_key' => sub { random_bytes(32) }; # 64 ?
255 # has 'headers.inner_random_stream_id' => STREAM_ID_CHACHA20;
256 # has 'headers.public_custom_data' => {};
257
258 # META
259 has 'meta.generator' => '', coerce => \&to_string;
260 has 'meta.header_hash' => '', coerce => \&to_string;
261 has 'meta.database_name' => '', coerce => \&to_string;
262 has 'meta.database_name_changed' => sub { gmtime }, coerce => \&to_time;
263 has 'meta.database_description' => '', coerce => \&to_string;
264 has 'meta.database_description_changed' => sub { gmtime }, coerce => \&to_time;
265 has 'meta.default_username' => '', coerce => \&to_string;
266 has 'meta.default_username_changed' => sub { gmtime }, coerce => \&to_time;
267 has 'meta.maintenance_history_days' => HISTORY_DEFAULT_MAX_AGE, coerce => \&to_number;
268 has 'meta.color' => '', coerce => \&to_string;
269 has 'meta.master_key_changed' => sub { gmtime }, coerce => \&to_time;
270 has 'meta.master_key_change_rec' => -1, coerce => \&to_number;
271 has 'meta.master_key_change_force' => -1, coerce => \&to_number;
272 # has 'meta.memory_protection' => {};
273 has 'meta.custom_icons' => [];
274 has 'meta.recycle_bin_enabled' => true, coerce => \&to_bool;
275 has 'meta.recycle_bin_uuid' => UUID_NULL, coerce => \&to_uuid;
276 has 'meta.recycle_bin_changed' => sub { gmtime }, coerce => \&to_time;
277 has 'meta.entry_templates_group' => UUID_NULL, coerce => \&to_uuid;
278 has 'meta.entry_templates_group_changed' => sub { gmtime }, coerce => \&to_time;
279 has 'meta.last_selected_group' => UUID_NULL, coerce => \&to_uuid;
280 has 'meta.last_top_visible_group' => UUID_NULL, coerce => \&to_uuid;
281 has 'meta.history_max_items' => HISTORY_DEFAULT_MAX_ITEMS, coerce => \&to_number;
282 has 'meta.history_max_size' => HISTORY_DEFAULT_MAX_SIZE, coerce => \&to_number;
283 has 'meta.settings_changed' => sub { gmtime }, coerce => \&to_time;
284 # has 'meta.binaries' => {};
285 # has 'meta.custom_data' => {};
286
287 has 'memory_protection.protect_title' => false, coerce => \&to_bool;
288 has 'memory_protection.protect_username' => false, coerce => \&to_bool;
289 has 'memory_protection.protect_password' => true, coerce => \&to_bool;
290 has 'memory_protection.protect_url' => false, coerce => \&to_bool;
291 has 'memory_protection.protect_notes' => false, coerce => \&to_bool;
292 # has 'memory_protection.auto_enable_visual_hiding' => false;
293
294 my @ATTRS = (
295 HEADER_TRANSFORM_SEED,
296 HEADER_TRANSFORM_ROUNDS,
297 HEADER_INNER_RANDOM_STREAM_KEY,
298 HEADER_INNER_RANDOM_STREAM_ID,
299 HEADER_PUBLIC_CUSTOM_DATA,
300 );
301 sub _set_nonlazy_attributes {
302 my $self = shift;
303 $self->$_ for list_attributes(ref $self), @ATTRS;
304 }
305
306 =method memory_protection
307
308 \%settings = $kdbx->memory_protection
309 $kdbx->memory_protection(\%settings);
310
311 $bool = $kdbx->memory_protection($string_key);
312 $kdbx->memory_protection($string_key => $bool);
313
314 Get or set memory protection settings. This globally (for the whole database) configures whether and which of
315 the standard strings should be memory-protected. The default setting is to memory-protect only I<Password>
316 strings.
317
318 Memory protection can be toggled individually for each entry string, and individual settings take precedence
319 over these global settings.
320
321 =cut
322
323 sub memory_protection {
324 my $self = shift;
325 $self->{meta}{memory_protection} = shift if @_ == 1 && is_plain_hashref($_[0]);
326 return $self->{meta}{memory_protection} //= {} if !@_;
327
328 my $string_key = shift;
329 my $key = 'protect_' . lc($string_key);
330
331 $self->meta->{memory_protection}{$key} = shift if @_;
332 $self->meta->{memory_protection}{$key};
333 }
334
335 =method minimum_version
336
337 $version = $kdbx->minimum_version;
338
339 Determine the minimum file version required to save a database losslessly. Using certain databases features
340 might increase this value. For example, setting the KDF to Argon2 will increase the minimum version to at
341 least C<KDBX_VERSION_4_0> (i.e. C<0x00040000>) because Argon2 was introduced with KDBX4.
342
343 This method never returns less than C<KDBX_VERSION_3_1> (i.e. C<0x00030001>). That file version is so
344 ubiquitious and well-supported, there are seldom reasons to dump in a lesser format nowadays.
345
346 B<WARNING:> If you dump a database with a minimum version higher than the current L</version>, the dumper will
347 typically issue a warning and automatically upgrade the database. This seems like the safest behavior in order
348 to avoid data loss, but lower versions have the benefit of being compatible with more software. It is possible
349 to prevent auto-upgrades by explicitly telling the dumper which version to use, but you do run the risk of
350 data loss. A database will never be automatically downgraded.
351
352 =cut
353
354 sub minimum_version {
355 my $self = shift;
356
357 return KDBX_VERSION_4_1 if any {
358 nonempty $_->{last_modification_time}
359 } values %{$self->custom_data};
360
361 return KDBX_VERSION_4_1 if any {
362 nonempty $_->{name} || nonempty $_->{last_modification_time}
363 } @{$self->custom_icons};
364
365 return KDBX_VERSION_4_1 if $self->groups->next(sub {
366 nonempty $_->previous_parent_group ||
367 nonempty $_->tags ||
368 (any { nonempty $_->{last_modification_time} } values %{$_->custom_data})
369 });
370
371 return KDBX_VERSION_4_1 if $self->entries(history => 1)->next(sub {
372 nonempty $_->previous_parent_group ||
373 (defined $_->quality_check && !$_->quality_check) ||
374 (any { nonempty $_->{last_modification_time} } values %{$_->custom_data})
375 });
376
377 return KDBX_VERSION_4_0 if $self->kdf->uuid ne KDF_UUID_AES;
378
379 return KDBX_VERSION_4_0 if nonempty $self->public_custom_data;
380
381 return KDBX_VERSION_4_0 if $self->objects->next(sub {
382 nonempty $_->custom_data
383 });
384
385 return KDBX_VERSION_3_1;
386 }
387
388 ##############################################################################
389
390 =method root
391
392 $group = $kdbx->root;
393 $kdbx->root($group);
394
395 Get or set a database's root group. You don't necessarily need to explicitly create or set a root group
396 because it autovivifies when adding entries and groups to the database.
397
398 Every database has only a single root group at a time. Some old KDB files might have multiple root groups.
399 When reading such files, a single implicit root group is created to contain the actual root groups. When
400 writing to such a format, if the root group looks like it was implicitly created then it won't be written and
401 the resulting file might have multiple root groups, as it was before loading. This allows working with older
402 files without changing their written internal structure while still adhering to modern semantics while the
403 database is opened.
404
405 The root group of a KDBX database contains all of the database's entries and other groups. If you replace the
406 root group, you are essentially replacing the entire database contents with something else.
407
408 =cut
409
410 sub root {
411 my $self = shift;
412 if (@_) {
413 $self->{root} = $self->_wrap_group(@_);
414 $self->{root}->kdbx($self);
415 }
416 $self->{root} //= $self->_implicit_root;
417 return $self->_wrap_group($self->{root});
418 }
419
420 # Called by File::KeePass::KDBX so that a File::KDBX an be treated as a File::KDBX::Group in that both types
421 # can have subgroups. File::KDBX already has a `groups' method that does something different from the
422 # File::KDBX::Groups `groups' method.
423 sub _kpx_groups {
424 my $self = shift;
425 return [] if !$self->{root};
426 return $self->_has_implicit_root ? $self->root->groups : [$self->root];
427 }
428
429 sub _has_implicit_root {
430 my $self = shift;
431 my $root = $self->root;
432 my $temp = __PACKAGE__->_implicit_root;
433 # If an implicit root group has been changed in any significant way, it is no longer implicit.
434 return $root->name eq $temp->name &&
435 $root->is_expanded ^ $temp->is_expanded &&
436 $root->notes eq $temp->notes &&
437 !@{$root->entries} &&
438 !defined $root->custom_icon_uuid &&
439 !keys %{$root->custom_data} &&
440 $root->icon_id == $temp->icon_id &&
441 $root->expires ^ $temp->expires &&
442 $root->default_auto_type_sequence eq $temp->default_auto_type_sequence &&
443 !defined $root->enable_auto_type &&
444 !defined $root->enable_searching;
445 }
446
447 sub _implicit_root {
448 my $self = shift;
449 require File::KDBX::Group;
450 return File::KDBX::Group->new(
451 name => 'Root',
452 is_expanded => true,
453 notes => 'Added as an implicit root group by '.__PACKAGE__.'.',
454 ref $self ? (kdbx => $self) : (),
455 );
456 }
457
458 =method trace_lineage
459
460 \@lineage = $kdbx->trace_lineage($group);
461 \@lineage = $kdbx->trace_lineage($group, $base_group);
462 \@lineage = $kdbx->trace_lineage($entry);
463 \@lineage = $kdbx->trace_lineage($entry, $base_group);
464
465 Get the direct line of ancestors from C<$base_group> (default: the root group) to a group or entry. The
466 lineage includes the base group but I<not> the target group or entry. Returns C<undef> if the target is not in
467 the database structure.
468
469 =cut
470
471 sub trace_lineage {
472 my $self = shift;
473 my $object = shift;
474 return $object->lineage(@_);
475 }
476
477 sub _trace_lineage {
478 my $self = shift;
479 my $object = shift;
480 my @lineage = @_;
481
482 push @lineage, $self->root if !@lineage;
483 my $base = $lineage[-1] or return [];
484
485 my $uuid = $object->uuid;
486 return \@lineage if any { $_->uuid eq $uuid } @{$base->groups}, @{$base->entries};
487
488 for my $subgroup (@{$base->groups}) {
489 my $result = $self->_trace_lineage($object, @lineage, $subgroup);
490 return $result if $result;
491 }
492 }
493
494 =method recycle_bin
495
496 $group = $kdbx->recycle_bin;
497 $kdbx->recycle_bin($group);
498
499 Get or set the recycle bin group. Returns C<undef> if there is no recycle bin and L</recycle_bin_enabled> is
500 false, otherwise the current recycle bin or an autovivified recycle bin group is returned.
501
502 =cut
503
504 sub recycle_bin {
505 my $self = shift;
506 if (my $group = shift) {
507 $self->recycle_bin_uuid($group->uuid);
508 return $group;
509 }
510 my $group;
511 my $uuid = $self->recycle_bin_uuid;
512 $group = $self->groups->grep(uuid => $uuid)->next if $uuid ne UUID_NULL;
513 if (!$group && $self->recycle_bin_enabled) {
514 $group = $self->add_group(
515 name => 'Recycle Bin',
516 icon_id => ICON_TRASHCAN_FULL,
517 enable_auto_type => false,
518 enable_searching => false,
519 );
520 $self->recycle_bin_uuid($group->uuid);
521 }
522 return $group;
523 }
524
525 =method entry_templates
526
527 $group = $kdbx->entry_templates;
528 $kdbx->entry_templates($group);
529
530 Get or set the entry templates group. May return C<undef> if unset.
531
532 =cut
533
534 sub entry_templates {
535 my $self = shift;
536 if (my $group = shift) {
537 $self->entry_templates_group($group->uuid);
538 return $group;
539 }
540 my $uuid = $self->entry_templates_group;
541 return if $uuid eq UUID_NULL;
542 return $self->groups->grep(uuid => $uuid)->next;
543 }
544
545 =method last_selected
546
547 $group = $kdbx->last_selected;
548 $kdbx->last_selected($group);
549
550 Get or set the last selected group. May return C<undef> if unset.
551
552 =cut
553
554 sub last_selected {
555 my $self = shift;
556 if (my $group = shift) {
557 $self->last_selected_group($group->uuid);
558 return $group;
559 }
560 my $uuid = $self->last_selected_group;
561 return if $uuid eq UUID_NULL;
562 return $self->groups->grep(uuid => $uuid)->next;
563 }
564
565 =method last_top_visible
566
567 $group = $kdbx->last_top_visible;
568 $kdbx->last_top_visible($group);
569
570 Get or set the last top visible group. May return C<undef> if unset.
571
572 =cut
573
574 sub last_top_visible {
575 my $self = shift;
576 if (my $group = shift) {
577 $self->last_top_visible_group($group->uuid);
578 return $group;
579 }
580 my $uuid = $self->last_top_visible_group;
581 return if $uuid eq UUID_NULL;
582 return $self->groups->grep(uuid => $uuid)->next;
583 }
584
585 ##############################################################################
586
587 =method add_group
588
589 $kdbx->add_group($group);
590 $kdbx->add_group(%group_attributes, %options);
591
592 Add a group to a database. This is equivalent to identifying a parent group and calling
593 L<File::KDBX::Group/add_group> on the parent group, forwarding the arguments. Available options:
594
595 =for :list
596 * C<group> - Group object or group UUID to add the group to (default: root group)
597
598 =cut
599
600 sub add_group {
601 my $self = shift;
602 my $group = @_ % 2 == 1 ? shift : undef;
603 my %args = @_;
604
605 # find the right group to add the group to
606 my $parent = delete $args{group} // $self->root;
607 $parent = $self->groups->grep({uuid => $parent})->next if !ref $parent;
608 $parent or throw 'Invalid group';
609
610 return $parent->add_group(defined $group ? $group : (), %args, kdbx => $self);
611 }
612
613 sub _wrap_group {
614 my $self = shift;
615 my $group = shift;
616 require File::KDBX::Group;
617 return File::KDBX::Group->wrap($group, $self);
618 }
619
620 =method groups
621
622 \&iterator = $kdbx->groups(%options);
623 \&iterator = $kdbx->groups($base_group, %options);
624
625 Get an L<File::KDBX::Iterator> over I<groups> within a database. Options:
626
627 =for :list
628 * C<base> - Only include groups within a base group (same as C<$base_group>) (default: L</root>)
629 * C<inclusive> - Include the base group in the results (default: true)
630 * C<algorithm> - Search algorithm, one of C<ids>, C<bfs> or C<dfs> (default: C<ids>)
631
632 =cut
633
634 sub groups {
635 my $self = shift;
636 my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
637 my $base = delete $args{base} // $self->root;
638
639 return $base->groups_deeply(%args);
640 }
641
642 ##############################################################################
643
644 =method add_entry
645
646 $kdbx->add_entry($entry, %options);
647 $kdbx->add_entry(%entry_attributes, %options);
648
649 Add a entry to a database. This is equivalent to identifying a parent group and calling
650 L<File::KDBX::Group/add_entry> on the parent group, forwarding the arguments. Available options:
651
652 =for :list
653 * C<group> - Group object or group UUID to add the entry to (default: root group)
654
655 =cut
656
657 sub add_entry {
658 my $self = shift;
659 my $entry = @_ % 2 == 1 ? shift : undef;
660 my %args = @_;
661
662 # find the right group to add the entry to
663 my $parent = delete $args{group} // $self->root;
664 $parent = $self->groups->grep({uuid => $parent})->next if !ref $parent;
665 $parent or throw 'Invalid group';
666
667 return $parent->add_entry(defined $entry ? $entry : (), %args, kdbx => $self);
668 }
669
670 sub _wrap_entry {
671 my $self = shift;
672 my $entry = shift;
673 require File::KDBX::Entry;
674 return File::KDBX::Entry->wrap($entry, $self);
675 }
676
677 =method entries
678
679 \&iterator = $kdbx->entries(%options);
680 \&iterator = $kdbx->entries($base_group, %options);
681
682 Get an L<File::KDBX::Iterator> over I<entries> within a database. Supports the same options as L</groups>,
683 plus some new ones:
684
685 =for :list
686 * C<auto_type> - Only include entries with auto-type enabled (default: false, include all)
687 * C<searching> - Only include entries within groups with searching enabled (default: false, include all)
688 * C<history> - Also include historical entries (default: false, include only current entries)
689
690 =cut
691
692 sub entries {
693 my $self = shift;
694 my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
695 my $base = delete $args{base} // $self->root;
696
697 return $base->entries_deeply(%args);
698 }
699
700 ##############################################################################
701
702 =method objects
703
704 \&iterator = $kdbx->objects(%options);
705 \&iterator = $kdbx->objects($base_group, %options);
706
707 Get an L<File::KDBX::Iterator> over I<objects> within a database. Groups and entries are considered objects,
708 so this is essentially a combination of L</groups> and L</entries>. This won't often be useful, but it can be
709 convenient for maintenance tasks. This method takes the same options as L</groups> and L</entries>.
710
711 =cut
712
713 sub objects {
714 my $self = shift;
715 my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
716 my $base = delete $args{base} // $self->root;
717
718 return $base->objects_deeply(%args);
719 }
720
721 sub __iter__ { $_[0]->objects }
722
723 ##############################################################################
724
725 =method custom_icon
726
727 \%icon = $kdbx->custom_icon($uuid);
728 $kdbx->custom_icon($uuid => \%icon);
729 $kdbx->custom_icon(%icon);
730 $kdbx->custom_icon(uuid => $value, %icon);
731
732 Get or set custom icons.
733
734 =cut
735
736 sub custom_icon {
737 my $self = shift;
738 my %args = @_ == 2 ? (uuid => shift, data => shift)
739 : @_ % 2 == 1 ? (uuid => shift, @_) : @_;
740
741 if (!$args{uuid} && !$args{data}) {
742 my %standard = (uuid => 1, data => 1, name => 1, last_modification_time => 1);
743 my @other_keys = grep { !$standard{$_} } keys %args;
744 if (@other_keys == 1) {
745 my $key = $args{key} = $other_keys[0];
746 $args{data} = delete $args{$key};
747 }
748 }
749
750 my $uuid = $args{uuid} or throw 'Must provide a custom icon UUID to access';
751 my $icon = (first { $_->{uuid} eq $uuid } @{$self->custom_icons}) // do {
752 push @{$self->custom_icons}, my $i = { uuid => $uuid };
753 $i;
754 };
755
756 my $fields = \%args;
757 $fields = $args{data} if is_plain_hashref($args{data});
758
759 while (my ($field, $value) = each %$fields) {
760 $icon->{$field} = $value;
761 }
762 return $icon;
763 }
764
765 =method custom_icon_data
766
767 $image_data = $kdbx->custom_icon_data($uuid);
768
769 Get a custom icon image data.
770
771 =cut
772
773 sub custom_icon_data {
774 my $self = shift;
775 my $uuid = shift // return;
776 my $icon = first { $_->{uuid} eq $uuid } @{$self->custom_icons} or return;
777 return $icon->{data};
778 }
779
780 =method add_custom_icon
781
782 $uuid = $kdbx->add_custom_icon($image_data, %attributes);
783 $uuid = $kdbx->add_custom_icon(%attributes);
784
785 Add a custom icon and get its UUID. If not provided, a random UUID will be generated. Possible attributes:
786
787 =for :list
788 * C<uuid> - Icon UUID (default: autogenerated)
789 * C<data> - Image data (same as C<$image_data>)
790 * C<name> - Name of the icon (text, KDBX4.1+)
791 * C<last_modification_time> - Just what it says (datetime, KDBX4.1+)
792
793 =cut
794
795 sub add_custom_icon {
796 my $self = shift;
797 my %args = @_ % 2 == 1 ? (data => shift, @_) : @_;
798
799 defined $args{data} or throw 'Must provide image data';
800
801 my $uuid = $args{uuid} // generate_uuid;
802 push @{$self->custom_icons}, {
803 @_,
804 uuid => $uuid,
805 data => $args{data},
806 };
807 return $uuid;
808 }
809
810 =method remove_custom_icon
811
812 $kdbx->remove_custom_icon($uuid);
813
814 Remove a custom icon.
815
816 =cut
817
818 sub remove_custom_icon {
819 my $self = shift;
820 my $uuid = shift;
821 my @deleted;
822 @{$self->custom_icons} = grep { $_->{uuid} eq $uuid ? do { push @deleted, $_; 0 } : 1 }
823 @{$self->custom_icons};
824 $self->add_deleted_object($uuid) if @deleted;
825 return @deleted;
826 }
827
828 ##############################################################################
829
830 =method custom_data
831
832 \%all_data = $kdbx->custom_data;
833 $kdbx->custom_data(\%all_data);
834
835 \%data = $kdbx->custom_data($key);
836 $kdbx->custom_data($key => \%data);
837 $kdbx->custom_data(%data);
838 $kdbx->custom_data(key => $value, %data);
839
840 Get and set custom data. Custom data is metadata associated with a database.
841
842 Each data item can have a few attributes associated with it.
843
844 =for :list
845 * C<key> - A unique text string identifier used to look up the data item (required)
846 * C<value> - A text string value (required)
847 * C<last_modification_time> (optional, KDBX4.1+)
848
849 =cut
850
851 sub custom_data {
852 my $self = shift;
853 $self->{meta}{custom_data} = shift if @_ == 1 && is_plain_hashref($_[0]);
854 return $self->{meta}{custom_data} //= {} if !@_;
855
856 my %args = @_ == 2 ? (key => shift, value => shift)
857 : @_ % 2 == 1 ? (key => shift, @_) : @_;
858
859 if (!$args{key} && !$args{value}) {
860 my %standard = (key => 1, value => 1, last_modification_time => 1);
861 my @other_keys = grep { !$standard{$_} } keys %args;
862 if (@other_keys == 1) {
863 my $key = $args{key} = $other_keys[0];
864 $args{value} = delete $args{$key};
865 }
866 }
867
868 my $key = $args{key} or throw 'Must provide a custom_data key to access';
869
870 return $self->{meta}{custom_data}{$key} = $args{value} if is_plain_hashref($args{value});
871
872 while (my ($field, $value) = each %args) {
873 $self->{meta}{custom_data}{$key}{$field} = $value;
874 }
875 return $self->{meta}{custom_data}{$key};
876 }
877
878 =method custom_data_value
879
880 $value = $kdbx->custom_data_value($key);
881
882 Exactly the same as L</custom_data> except returns just the custom data's value rather than a structure of
883 attributes. This is a shortcut for:
884
885 my $data = $kdbx->custom_data($key);
886 my $value = defined $data ? $data->{value} : undef;
887
888 =cut
889
890 sub custom_data_value {
891 my $self = shift;
892 my $data = $self->custom_data(@_) // return;
893 return $data->{value};
894 }
895
896 =method public_custom_data
897
898 \%all_data = $kdbx->public_custom_data;
899 $kdbx->public_custom_data(\%all_data);
900
901 $value = $kdbx->public_custom_data($key);
902 $kdbx->public_custom_data($key => $value);
903
904 Get and set public custom data. Public custom data is similar to custom data but different in some important
905 ways. Public custom data:
906
907 =for :list
908 * can store strings, booleans and up to 64-bit integer values (custom data can only store text values)
909 * is NOT encrypted within a KDBX file (hence the "public" part of the name)
910 * is a plain hash/dict of key-value pairs with no other associated fields (like modification times)
911
912 =cut
913
914 sub public_custom_data {
915 my $self = shift;
916 $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA} = shift if @_ == 1 && is_plain_hashref($_[0]);
917 return $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA} //= {} if !@_;
918
919 my $key = shift or throw 'Must provide a public_custom_data key to access';
920 $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA}{$key} = shift if @_;
921 return $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA}{$key};
922 }
923
924 ##############################################################################
925
926 # TODO
927
928 # sub merge_to {
929 # my $self = shift;
930 # my $other = shift;
931 # my %options = @_; # prefer_old / prefer_new
932 # $other->merge_from($self);
933 # }
934
935 # sub merge_from {
936 # my $self = shift;
937 # my $other = shift;
938
939 # die 'Not implemented';
940 # }
941
942 =method add_deleted_object
943
944 $kdbx->add_deleted_object($uuid);
945
946 Add a UUID to the deleted objects list. This list is used to support automatic database merging.
947
948 You typically do not need to call this yourself because the list will be populated automatically as objects
949 are removed.
950
951 =cut
952
953 sub add_deleted_object {
954 my $self = shift;
955 my $uuid = shift;
956
957 # ignore null and meta stream UUIDs
958 return if $uuid eq UUID_NULL || $uuid eq '0' x 16;
959
960 $self->deleted_objects->{$uuid} = {
961 uuid => $uuid,
962 deletion_time => scalar gmtime,
963 };
964 }
965
966 =method remove_deleted_object
967
968 $kdbx->remove_deleted_object($uuid);
969
970 Remove a UUID from the deleted objects list. This list is used to support automatic database merging.
971
972 You typically do not need to call this yourself because the list will be maintained automatically as objects
973 are added.
974
975 =cut
976
977 sub remove_deleted_object {
978 my $self = shift;
979 my $uuid = shift;
980 delete $self->deleted_objects->{$uuid};
981 }
982
983 =method clear_deleted_objects
984
985 Remove all UUIDs from the deleted objects list. This list is used to support automatic database merging, but
986 if you don't need merging then you can clear deleted objects to reduce the database file size.
987
988 =cut
989
990 sub clear_deleted_objects {
991 my $self = shift;
992 %{$self->deleted_objects} = ();
993 }
994
995 ##############################################################################
996
997 =method resolve_reference
998
999 $string = $kdbx->resolve_reference($reference);
1000 $string = $kdbx->resolve_reference($wanted, $search_in, $expression);
1001
1002 Resolve a L<field reference|https://keepass.info/help/base/fieldrefs.html>. A field reference is a kind of
1003 string placeholder. You can use a field reference to refer directly to a standard field within an entry. Field
1004 references are resolved automatically while expanding entry strings (i.e. replacing placeholders), but you can
1005 use this method to resolve on-the-fly references that aren't part of any actual string in the database.
1006
1007 If the reference does not resolve to any field, C<undef> is returned. If the reference resolves to multiple
1008 fields, only the first one is returned (in the same order as iterated by L</entries>). To avoid ambiguity, you
1009 can refer to a specific entry by its UUID.
1010
1011 The syntax of a reference is: C<< {REF:<WantedField>@<SearchIn>:<Text>} >>. C<Text> is a
1012 L</"Simple Expression">. C<WantedField> and C<SearchIn> are both single character codes representing a field:
1013
1014 =for :list
1015 * C<T> - Title
1016 * C<U> - UserName
1017 * C<P> - Password
1018 * C<A> - URL
1019 * C<N> - Notes
1020 * C<I> - UUID
1021 * C<O> - Other custom strings
1022
1023 Since C<O> does not represent any specific field, it cannot be used as the C<WantedField>.
1024
1025 Examples:
1026
1027 To get the value of the I<UserName> string of the first entry with "My Bank" in the title:
1028
1029 my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
1030 # OR the {REF:...} wrapper is optional
1031 my $username = $kdbx->resolve_reference('U@T:"My Bank"');
1032 # OR separate the arguments
1033 my $username = $kdbx->resolve_reference(U => T => '"My Bank"');
1034
1035 Note how the text is a L</"Simple Expression">, so search terms with spaces must be surrounded in double
1036 quotes.
1037
1038 To get the I<Password> string of a specific entry (identified by its UUID):
1039
1040 my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');
1041
1042 =cut
1043
1044 sub resolve_reference {
1045 my $self = shift;
1046 my $wanted = shift // return;
1047 my $search_in = shift;
1048 my $text = shift;
1049
1050 if (!defined $text) {
1051 $wanted =~ s/^\{REF:([^\}]+)\}$/$1/i;
1052 ($wanted, $search_in, $text) = $wanted =~ /^([TUPANI])\@([TUPANIO]):(.*)$/i;
1053 }
1054 $wanted && $search_in && nonempty($text) or return;
1055
1056 my %fields = (
1057 T => 'expand_title',
1058 U => 'expand_username',
1059 P => 'expand_password',
1060 A => 'expand_url',
1061 N => 'expand_notes',
1062 I => 'uuid',
1063 O => 'other_strings',
1064 );
1065 $wanted = $fields{$wanted} or return;
1066 $search_in = $fields{$search_in} or return;
1067
1068 my $query = $search_in eq 'uuid' ? query($search_in => uuid($text))
1069 : simple_expression_query($text, '=~', $search_in);
1070
1071 my $entry = $self->entries->grep($query)->next;
1072 $entry or return;
1073
1074 return $entry->$wanted;
1075 }
1076
1077 our %PLACEHOLDERS = (
1078 # 'PLACEHOLDER' => sub { my ($entry, $arg) = @_; ... };
1079 'TITLE' => sub { $_[0]->expand_title },
1080 'USERNAME' => sub { $_[0]->expand_username },
1081 'PASSWORD' => sub { $_[0]->expand_password },
1082 'NOTES' => sub { $_[0]->expand_notes },
1083 'S:' => sub { $_[0]->string_value($_[1]) },
1084 'URL' => sub { $_[0]->expand_url },
1085 'URL:RMVSCM' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
1086 'URL:WITHOUTSCHEME' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
1087 'URL:SCM' => sub { (split_url($_[0]->url))[0] },
1088 'URL:SCHEME' => sub { (split_url($_[0]->url))[0] }, # non-standard
1089 'URL:HOST' => sub { (split_url($_[0]->url))[2] },
1090 'URL:PORT' => sub { (split_url($_[0]->url))[3] },
1091 'URL:PATH' => sub { (split_url($_[0]->url))[4] },
1092 'URL:QUERY' => sub { (split_url($_[0]->url))[5] },
1093 'URL:HASH' => sub { (split_url($_[0]->url))[6] }, # non-standard
1094 'URL:FRAGMENT' => sub { (split_url($_[0]->url))[6] }, # non-standard
1095 'URL:USERINFO' => sub { (split_url($_[0]->url))[1] },
1096 'URL:USERNAME' => sub { (split_url($_[0]->url))[7] },
1097 'URL:PASSWORD' => sub { (split_url($_[0]->url))[8] },
1098 'UUID' => sub { local $_ = format_uuid($_[0]->uuid); s/-//g; $_ },
1099 'REF:' => sub { $_[0]->kdbx->resolve_reference($_[1]) },
1100 'INTERNETEXPLORER' => sub { load_optional('IPC::Cmd'); IPC::Cmd::can_run('iexplore') },
1101 'FIREFOX' => sub { load_optional('IPC::Cmd'); IPC::Cmd::can_run('firefox') },
1102 'GOOGLECHROME' => sub { load_optional('IPC::Cmd'); IPC::Cmd::can_run('google-chrome') },
1103 'OPERA' => sub { load_optional('IPC::Cmd'); IPC::Cmd::can_run('opera') },
1104 'SAFARI' => sub { load_optional('IPC::Cmd'); IPC::Cmd::can_run('safari') },
1105 'APPDIR' => sub { load_optional('FindBin'); $FindBin::Bin },
1106 'GROUP' => sub { my $p = $_[0]->group; $p ? $p->name : undef },
1107 'GROUP_PATH' => sub { $_[0]->path },
1108 'GROUP_NOTES' => sub { my $p = $_[0]->group; $p ? $p->notes : undef },
1109 # 'GROUP_SEL'
1110 # 'GROUP_SEL_PATH'
1111 # 'GROUP_SEL_NOTES'
1112 # 'DB_PATH'
1113 # 'DB_DIR'
1114 # 'DB_NAME'
1115 # 'DB_BASENAME'
1116 # 'DB_EXT'
1117 'ENV:' => sub { $ENV{$_[1]} },
1118 'ENV_DIRSEP' => sub { load_optional('File::Spec')->catfile('', '') },
1119 'ENV_PROGRAMFILES_X86' => sub { $ENV{'ProgramFiles(x86)'} || $ENV{'ProgramFiles'} },
1120 # 'T-REPLACE-RX:'
1121 # 'T-CONV:'
1122 'DT_SIMPLE' => sub { localtime->strftime('%Y%m%d%H%M%S') },
1123 'DT_YEAR' => sub { localtime->strftime('%Y') },
1124 'DT_MONTH' => sub { localtime->strftime('%m') },
1125 'DT_DAY' => sub { localtime->strftime('%d') },
1126 'DT_HOUR' => sub { localtime->strftime('%H') },
1127 'DT_MINUTE' => sub { localtime->strftime('%M') },
1128 'DT_SECOND' => sub { localtime->strftime('%S') },
1129 'DT_UTC_SIMPLE' => sub { gmtime->strftime('%Y%m%d%H%M%S') },
1130 'DT_UTC_YEAR' => sub { gmtime->strftime('%Y') },
1131 'DT_UTC_MONTH' => sub { gmtime->strftime('%m') },
1132 'DT_UTC_DAY' => sub { gmtime->strftime('%d') },
1133 'DT_UTC_HOUR' => sub { gmtime->strftime('%H') },
1134 'DT_UTC_MINUTE' => sub { gmtime->strftime('%M') },
1135 'DT_UTC_SECOND' => sub { gmtime->strftime('%S') },
1136 # 'PICKCHARS'
1137 # 'PICKCHARS:'
1138 # 'PICKFIELD'
1139 # 'NEWPASSWORD'
1140 # 'NEWPASSWORD:'
1141 # 'PASSWORD_ENC'
1142 'HMACOTP' => sub { $_[0]->hmac_otp },
1143 'TIMEOTP' => sub { $_[0]->time_otp },
1144 'C:' => sub { '' }, # comment
1145 # 'BASE'
1146 # 'BASE:'
1147 # 'CLIPBOARD'
1148 # 'CLIPBOARD-SET:'
1149 # 'CMD:'
1150 );
1151
1152 ##############################################################################
1153
1154 =method lock
1155
1156 $kdbx->lock;
1157
1158 Encrypt all protected strings and binaries in a database. The encrypted data is stored in
1159 a L<File::KDBX::Safe> associated with the database and the actual values will be replaced with C<undef> to
1160 indicate their protected state. Returns itself to allow method chaining.
1161
1162 You can call C<lock> on an already-locked database to memory-protect any unprotected strings and binaries
1163 added after the last time the database was locked.
1164
1165 =cut
1166
1167 sub _safe {
1168 my $self = shift;
1169 $SAFE{$self} = shift if @_;
1170 $SAFE{$self};
1171 }
1172
1173 sub _remove_safe { delete $SAFE{$_[0]} }
1174
1175 sub lock {
1176 my $self = shift;
1177
1178 $self->_safe and return $self;
1179
1180 my @strings;
1181
1182 $self->entries(history => 1)->each(sub {
1183 push @strings, grep { $_->{protect} } values %{$_->strings}, values %{$_->binaries};
1184 });
1185
1186 $self->_safe(File::KDBX::Safe->new(\@strings));
1187
1188 return $self;
1189 }
1190
1191 =method unlock
1192
1193 $kdbx->unlock;
1194
1195 Decrypt all protected strings and binaries in a database, replacing C<undef> value placeholders with their
1196 actual, unprotected values. Returns itself to allow method chaining.
1197
1198 =cut
1199
1200 sub unlock {
1201 my $self = shift;
1202 my $safe = $self->_safe or return $self;
1203
1204 $safe->unlock;
1205 $self->_remove_safe;
1206
1207 return $self;
1208 }
1209
1210 =method unlock_scoped
1211
1212 $guard = $kdbx->unlock_scoped;
1213
1214 Unlock a database temporarily, relocking when the guard is released (typically at the end of a scope). Returns
1215 C<undef> if the database is already unlocked.
1216
1217 See L</lock> and L</unlock>.
1218
1219 Example:
1220
1221 {
1222 my $guard = $kdbx->unlock_scoped;
1223 ...;
1224 }
1225 # $kdbx is now memory-locked
1226
1227 =cut
1228
1229 sub unlock_scoped {
1230 throw 'Programmer error: Cannot call unlock_scoped in void context' if !defined wantarray;
1231 my $self = shift;
1232 return if !$self->is_locked;
1233 require Scope::Guard;
1234 my $guard = Scope::Guard->new(sub { $self->lock });
1235 $self->unlock;
1236 return $guard;
1237 }
1238
1239 =method peek
1240
1241 $string = $kdbx->peek(\%string);
1242 $string = $kdbx->peek(\%binary);
1243
1244 Peek at the value of a protected string or binary without unlocking the whole database. The argument can be
1245 a string or binary hashref as returned by L<File::KDBX::Entry/string> or L<File::KDBX::Entry/binary>.
1246
1247 =cut
1248
1249 sub peek {
1250 my $self = shift;
1251 my $string = shift;
1252 my $safe = $self->_safe or return;
1253 return $safe->peek($string);
1254 }
1255
1256 =method is_locked
1257
1258 $bool = $kdbx->is_locked;
1259
1260 Get whether or not a database's contents are in a locked (i.e. memory-protected) state. If this is true, then
1261 some or all of the protected strings and binaries within the database will be unavailable (literally have
1262 C<undef> values) until L</unlock> is called.
1263
1264 =cut
1265
1266 sub is_locked { !!$_[0]->_safe }
1267
1268 ##############################################################################
1269
1270 # sub check {
1271 # - Fixer tool. Can repair inconsistencies, including:
1272 # - Orphaned binaries... not really a thing anymore since we now distribute binaries amongst entries
1273 # - Unused custom icons (OFF, data loss)
1274 # - Duplicate icons
1275 # - All data types are valid
1276 # - date times are correct
1277 # - boolean fields
1278 # - All UUIDs refer to things that exist
1279 # - previous parent group
1280 # - recycle bin
1281 # - last selected group
1282 # - last visible group
1283 # - Enforce history size limits (ON)
1284 # - Check headers/meta (ON)
1285 # - Duplicate deleted objects (ON)
1286 # - Duplicate window associations (OFF)
1287 # - Header UUIDs match known ciphers/KDFs?
1288 # }
1289
1290 =method remove_empty_groups
1291
1292 $kdbx->remove_empty_groups;
1293
1294 Remove groups with no subgroups and no entries.
1295
1296 =cut
1297
1298 sub remove_empty_groups {
1299 my $self = shift;
1300 my @removed;
1301 $self->groups(algorithm => 'dfs')
1302 ->where(-true => 'is_empty')
1303 ->each(sub { push @removed, $_->remove });
1304 return @removed;
1305 }
1306
1307 =method remove_unused_icons
1308
1309 $kdbx->remove_unused_icons;
1310
1311 Remove icons that are not associated with any entry or group in the database.
1312
1313 =cut
1314
1315 sub remove_unused_icons {
1316 my $self = shift;
1317 my %icons = map { $_->{uuid} => 0 } @{$self->custom_icons};
1318
1319 $self->objects->each(sub { ++$icons{$_->custom_icon_uuid // ''} });
1320
1321 my @removed;
1322 push @removed, $self->remove_custom_icon($_) for grep { $icons{$_} == 0 } keys %icons;
1323 return @removed;
1324 }
1325
1326 =method remove_duplicate_icons
1327
1328 $kdbx->remove_duplicate_icons;
1329
1330 Remove duplicate icons as determined by hashing the icon data.
1331
1332 =cut
1333
1334 sub remove_duplicate_icons {
1335 my $self = shift;
1336
1337 my %seen;
1338 my %dup;
1339 for my $icon (@{$self->custom_icons}) {
1340 my $digest = digest_data('SHA256', $icon->{data});
1341 if (my $other = $seen{$digest}) {
1342 $dup{$icon->{uuid}} = $other->{uuid};
1343 }
1344 else {
1345 $seen{$digest} = $icon;
1346 }
1347 }
1348
1349 my @removed;
1350 while (my ($old_uuid, $new_uuid) = each %dup) {
1351 $self->objects
1352 ->where(custom_icon_uuid => $old_uuid)
1353 ->each(sub { $_->custom_icon_uuid($new_uuid) });
1354 push @removed, $self->remove_custom_icon($old_uuid);
1355 }
1356 return @removed;
1357 }
1358
1359 =method prune_history
1360
1361 $kdbx->prune_history(%options);
1362
1363 Remove just as many older historical entries as necessary to get under certain limits.
1364
1365 =for :list
1366 * C<max_items> - Maximum number of historical entries to keep (default: value of L</history_max_items>, no
1367 limit: -1)
1368 * C<max_size> - Maximum total size (in bytes) of historical entries to keep (default: value of
1369 L</history_max_size>, no limit: -1)
1370 * C<max_age> - Maximum age (in days) of historical entries to keep (default: 365, no limit: -1)
1371
1372 =cut
1373
1374 sub prune_history {
1375 my $self = shift;
1376 my %args = @_;
1377
1378 my $max_items = $args{max_items} // $self->history_max_items // HISTORY_DEFAULT_MAX_ITEMS;
1379 my $max_size = $args{max_size} // $self->history_max_size // HISTORY_DEFAULT_MAX_SIZE;
1380 my $max_age = $args{max_age} // $self->maintenance_history_days // HISTORY_DEFAULT_MAX_AGE;
1381
1382 my @removed;
1383 $self->entries->each(sub {
1384 push @removed, $_->prune_history(
1385 max_items => $max_items,
1386 max_size => $max_size,
1387 max_age => $max_age,
1388 );
1389 });
1390 return @removed;
1391 }
1392
1393 =method randomize_seeds
1394
1395 $kdbx->randomize_seeds;
1396
1397 Set various keys, seeds and IVs to random values. These values are used by the cryptographic functions that
1398 secure the database when dumped. The attributes that will be randomized are:
1399
1400 =for :list
1401 * L</encryption_iv>
1402 * L</inner_random_stream_key>
1403 * L</master_seed>
1404 * L</stream_start_bytes>
1405 * L</transform_seed>
1406
1407 Randomizing these values has no effect on a loaded database. These are only used when a database is dumped.
1408 You normally do not need to call this method explicitly because the dumper does it explicitly by default.
1409
1410 =cut
1411
1412 sub randomize_seeds {
1413 my $self = shift;
1414 $self->encryption_iv(random_bytes(16));
1415 $self->inner_random_stream_key(random_bytes(64));
1416 $self->master_seed(random_bytes(32));
1417 $self->stream_start_bytes(random_bytes(32));
1418 $self->transform_seed(random_bytes(32));
1419 }
1420
1421 ##############################################################################
1422
1423 =method key
1424
1425 $key = $kdbx->key;
1426 $key = $kdbx->key($key);
1427 $key = $kdbx->key($primitive);
1428
1429 Get or set a L<File::KDBX::Key>. This is the master key (e.g. a password or a key file that can decrypt
1430 a database). You can also pass a primitive castable to a B<Key>. See L<File::KDBX::Key/new> for an explanation
1431 of what the primitive can be.
1432
1433 You generally don't need to call this directly because you can provide the key directly to the loader or
1434 dumper when loading or dumping a KDBX file.
1435
1436 =cut
1437
1438 sub key {
1439 my $self = shift;
1440 $KEYS{$self} = File::KDBX::Key->new(@_) if @_;
1441 $KEYS{$self};
1442 }
1443
1444 =method composite_key
1445
1446 $key = $kdbx->composite_key($key);
1447 $key = $kdbx->composite_key($primitive);
1448
1449 Construct a L<File::KDBX::Key::Composite> from a B<Key> or primitive. See L<File::KDBX::Key/new> for an
1450 explanation of what the primitive can be. If the primitive does not represent a composite key, it will be
1451 wrapped.
1452
1453 You generally don't need to call this directly. The loader and dumper use it to transform a master key into
1454 a raw encryption key.
1455
1456 =cut
1457
1458 sub composite_key {
1459 my $self = shift;
1460 require File::KDBX::Key::Composite;
1461 return File::KDBX::Key::Composite->new(@_);
1462 }
1463
1464 =method kdf
1465
1466 $kdf = $kdbx->kdf(%options);
1467 $kdf = $kdbx->kdf(\%parameters, %options);
1468
1469 Get a L<File::KDBX::KDF> (key derivation function).
1470
1471 Options:
1472
1473 =for :list
1474 * C<params> - KDF parameters, same as C<\%parameters> (default: value of L</kdf_parameters>)
1475
1476 =cut
1477
1478 sub kdf {
1479 my $self = shift;
1480 my %args = @_ % 2 == 1 ? (params => shift, @_) : @_;
1481
1482 my $params = $args{params};
1483 my $compat = $args{compatible} // 1;
1484
1485 $params //= $self->kdf_parameters;
1486 $params = {%{$params || {}}};
1487
1488 if (empty $params || !defined $params->{+KDF_PARAM_UUID}) {
1489 $params->{+KDF_PARAM_UUID} = KDF_UUID_AES;
1490 }
1491 if ($params->{+KDF_PARAM_UUID} eq KDF_UUID_AES) {
1492 # AES_CHALLENGE_RESPONSE is equivalent to AES if there are no challenge-response keys, and since
1493 # non-KeePassXC implementations don't support challenge-response keys anyway, there's no problem with
1494 # always using AES_CHALLENGE_RESPONSE for all KDBX4+ databases.
1495 # For compatibility, we should not *write* AES_CHALLENGE_RESPONSE, but the dumper handles that.
1496 if ($self->version >= KDBX_VERSION_4_0) {
1497 $params->{+KDF_PARAM_UUID} = KDF_UUID_AES_CHALLENGE_RESPONSE;
1498 }
1499 $params->{+KDF_PARAM_AES_SEED} //= $self->transform_seed;
1500 $params->{+KDF_PARAM_AES_ROUNDS} //= $self->transform_rounds;
1501 }
1502
1503 require File::KDBX::KDF;
1504 return File::KDBX::KDF->new(%$params);
1505 }
1506
1507 sub transform_seed {
1508 my $self = shift;
1509 $self->headers->{+HEADER_TRANSFORM_SEED} =
1510 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_SEED} = shift if @_;
1511 $self->headers->{+HEADER_TRANSFORM_SEED} =
1512 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_SEED} //= random_bytes(32);
1513 }
1514
1515 sub transform_rounds {
1516 my $self = shift;
1517 $self->headers->{+HEADER_TRANSFORM_ROUNDS} =
1518 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_ROUNDS} = shift if @_;
1519 $self->headers->{+HEADER_TRANSFORM_ROUNDS} =
1520 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_ROUNDS} //= 100_000;
1521 }
1522
1523 =method cipher
1524
1525 $cipher = $kdbx->cipher(key => $key);
1526 $cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);
1527
1528 Get a L<File::KDBX::Cipher> capable of encrypting and decrypting the body of a database file.
1529
1530 A key is required. This should be a raw encryption key made up of a fixed number of octets (depending on the
1531 cipher), not a L<File::KDBX::Key> or primitive.
1532
1533 If not passed, the UUID comes from C<< $kdbx->headers->{cipher_id} >> and the encryption IV comes from
1534 C<< $kdbx->headers->{encryption_iv} >>.
1535
1536 You generally don't need to call this directly. The loader and dumper use it to decrypt and encrypt KDBX
1537 files.
1538
1539 =cut
1540
1541 sub cipher {
1542 my $self = shift;
1543 my %args = @_;
1544
1545 $args{uuid} //= $self->headers->{+HEADER_CIPHER_ID};
1546 $args{iv} //= $self->headers->{+HEADER_ENCRYPTION_IV};
1547
1548 require File::KDBX::Cipher;
1549 return File::KDBX::Cipher->new(%args);
1550 }
1551
1552 =method random_stream
1553
1554 $cipher = $kdbx->random_stream;
1555 $cipher = $kdbx->random_stream(id => $stream_id, key => $key);
1556
1557 Get a L<File::KDBX::Cipher::Stream> for decrypting and encrypting protected values.
1558
1559 If not passed, the ID and encryption key comes from C<< $kdbx->headers->{inner_random_stream_id} >> and
1560 C<< $kdbx->headers->{inner_random_stream_key} >> (respectively) for KDBX3 files and from
1561 C<< $kdbx->inner_headers->{inner_random_stream_key} >> and
1562 C<< $kdbx->inner_headers->{inner_random_stream_id} >> (respectively) for KDBX4 files.
1563
1564 You generally don't need to call this directly. The loader and dumper use it to scramble protected strings.
1565
1566 =cut
1567
1568 sub random_stream {
1569 my $self = shift;
1570 my %args = @_;
1571
1572 $args{stream_id} //= delete $args{id} // $self->inner_random_stream_id;
1573 $args{key} //= $self->inner_random_stream_key;
1574
1575 require File::KDBX::Cipher;
1576 File::KDBX::Cipher->new(%args);
1577 }
1578
1579 sub inner_random_stream_id {
1580 my $self = shift;
1581 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID}
1582 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID} = shift if @_;
1583 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID}
1584 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID} //= do {
1585 my $version = $self->minimum_version;
1586 $version < KDBX_VERSION_4_0 ? STREAM_ID_SALSA20 : STREAM_ID_CHACHA20;
1587 };
1588 }
1589
1590 sub inner_random_stream_key {
1591 my $self = shift;
1592 if (@_) {
1593 # These are probably the same SvPV so erasing one will CoW, but erasing the second should do the
1594 # trick anyway.
1595 erase \$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY};
1596 erase \$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY};
1597 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY}
1598 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY} = shift;
1599 }
1600 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY}
1601 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY} //= random_bytes(64); # 32
1602 }
1603
1604 #########################################################################################
1605
1606 sub _handle_signal {
1607 my $self = shift;
1608 my $object = shift;
1609 my $type = shift;
1610
1611 my %handlers = (
1612 'entry.added' => \&_handle_object_added,
1613 'group.added' => \&_handle_object_added,
1614 'entry.removed' => \&_handle_object_removed,
1615 'group.removed' => \&_handle_object_removed,
1616 'entry.uuid.changed' => \&_handle_entry_uuid_changed,
1617 'group.uuid.changed' => \&_handle_group_uuid_changed,
1618 );
1619 my $handler = $handlers{$type} or return;
1620 $self->$handler($object, @_);
1621 }
1622
1623 sub _handle_object_added {
1624 my $self = shift;
1625 my $object = shift;
1626 $self->remove_deleted_object($object->uuid);
1627 }
1628
1629 sub _handle_object_removed {
1630 my $self = shift;
1631 my $object = shift;
1632 my $old_uuid = $object->{uuid} // return;
1633
1634 my $meta = $self->meta;
1635 $self->recycle_bin_uuid(UUID_NULL) if $old_uuid eq ($meta->{recycle_bin_uuid} // '');
1636 $self->entry_templates_group(UUID_NULL) if $old_uuid eq ($meta->{entry_templates_group} // '');
1637 $self->last_selected_group(UUID_NULL) if $old_uuid eq ($meta->{last_selected_group} // '');
1638 $self->last_top_visible_group(UUID_NULL) if $old_uuid eq ($meta->{last_top_visible_group} // '');
1639
1640 $self->add_deleted_object($old_uuid);
1641 }
1642
1643 sub _handle_entry_uuid_changed {
1644 my $self = shift;
1645 my $object = shift;
1646 my $new_uuid = shift;
1647 my $old_uuid = shift // return;
1648
1649 my $old_pretty = format_uuid($old_uuid);
1650 my $new_pretty = format_uuid($new_uuid);
1651 my $fieldref_match = qr/\{REF:([TUPANI])\@I:\Q$old_pretty\E\}/is;
1652
1653 $self->entries->each(sub {
1654 $_->previous_parent_group($new_uuid) if $old_uuid eq ($_->{previous_parent_group} // '');
1655
1656 for my $string (values %{$_->strings}) {
1657 next if !defined $string->{value} || $string->{value} !~ $fieldref_match;
1658 my $txn = $_->begin_work;
1659 $string->{value} =~ s/$fieldref_match/{REF:$1\@I:$new_pretty}/g;
1660 $txn->commit;
1661 }
1662 });
1663 }
1664
1665 sub _handle_group_uuid_changed {
1666 my $self = shift;
1667 my $object = shift;
1668 my $new_uuid = shift;
1669 my $old_uuid = shift // return;
1670
1671 my $meta = $self->meta;
1672 $self->recycle_bin_uuid($new_uuid) if $old_uuid eq ($meta->{recycle_bin_uuid} // '');
1673 $self->entry_templates_group($new_uuid) if $old_uuid eq ($meta->{entry_templates_group} // '');
1674 $self->last_selected_group($new_uuid) if $old_uuid eq ($meta->{last_selected_group} // '');
1675 $self->last_top_visible_group($new_uuid) if $old_uuid eq ($meta->{last_top_visible_group} // '');
1676
1677 $self->groups->each(sub {
1678 $_->last_top_visible_entry($new_uuid) if $old_uuid eq ($_->{last_top_visible_entry} // '');
1679 $_->previous_parent_group($new_uuid) if $old_uuid eq ($_->{previous_parent_group} // '');
1680 });
1681 $self->entries->each(sub {
1682 $_->previous_parent_group($new_uuid) if $old_uuid eq ($_->{previous_parent_group} // '');
1683 });
1684 }
1685
1686 #########################################################################################
1687
1688 =attr sig1
1689
1690 =attr sig2
1691
1692 =attr version
1693
1694 =attr headers
1695
1696 =attr inner_headers
1697
1698 =attr meta
1699
1700 =attr binaries
1701
1702 =attr deleted_objects
1703
1704 Hash of UUIDs for objects that have been deleted. This includes groups, entries and even custom icons.
1705
1706 =attr raw
1707
1708 Bytes contained within the encrypted layer of a KDBX file. This is only set when using
1709 L<File::KDBX::Loader::Raw>.
1710
1711 =attr comment
1712
1713 A text string associated with the database. Often unset.
1714
1715 =attr cipher_id
1716
1717 The UUID of a cipher used to encrypt the database when stored as a file.
1718
1719 See L</File::KDBX::Cipher>.
1720
1721 =attr compression_flags
1722
1723 Configuration for whether or not and how the database gets compressed. See
1724 L<File::KDBX::Constants/":compression">.
1725
1726 =attr master_seed
1727
1728 The master seed is a string of 32 random bytes that is used as salt in hashing the master key when loading
1729 and saving the database. If a challenge-response key is used in the master key, the master seed is also the
1730 challenge.
1731
1732 The master seed I<should> be changed each time the database is saved to file.
1733
1734 =attr transform_seed
1735
1736 The transform seed is a string of 32 random bytes that is used in the key derivation function, either as the
1737 salt or the key (depending on the algorithm).
1738
1739 The transform seed I<should> be changed each time the database is saved to file.
1740
1741 =attr transform_rounds
1742
1743 The number of rounds or iterations used in the key derivation function. Increasing this number makes loading
1744 and saving the database slower by design in order to make dictionary and brute force attacks more costly.
1745
1746 =attr encryption_iv
1747
1748 The initialization vector used by the cipher.
1749
1750 The encryption IV I<should> be changed each time the database is saved to file.
1751
1752 =attr inner_random_stream_key
1753
1754 The encryption key (possibly including the IV, depending on the cipher) used to encrypt the protected strings
1755 within the database.
1756
1757 =attr stream_start_bytes
1758
1759 A string of 32 random bytes written in the header and encrypted in the body. If the bytes do not match when
1760 loading a file then the wrong master key was used or the file is corrupt. Only KDBX 2 and KDBX 3 files use
1761 this. KDBX 4 files use an improved HMAC method to verify the master key and data integrity of the header and
1762 entire file body.
1763
1764 =attr inner_random_stream_id
1765
1766 A number indicating the cipher algorithm used to encrypt the protected strings within the database, usually
1767 Salsa20 or ChaCha20. See L<File::KDBX::Constants/":random_stream">.
1768
1769 =attr kdf_parameters
1770
1771 A hash/dict of key-value pairs used to configure the key derivation function. This is the KDBX4+ way to
1772 configure the KDF, superceding L</transform_seed> and L</transform_rounds>.
1773
1774 =attr generator
1775
1776 The name of the software used to generate the KDBX file.
1777
1778 =attr header_hash
1779
1780 The header hash used to verify that the file header is not corrupt. (KDBX 2 - KDBX 3.1, removed KDBX 4.0)
1781
1782 =attr database_name
1783
1784 Name of the database.
1785
1786 =attr database_name_changed
1787
1788 Timestamp indicating when the database name was last changed.
1789
1790 =attr database_description
1791
1792 Description of the database
1793
1794 =attr database_description_changed
1795
1796 Timestamp indicating when the database description was last changed.
1797
1798 =attr default_username
1799
1800 When a new entry is created, the I<UserName> string will be populated with this value.
1801
1802 =attr default_username_changed
1803
1804 Timestamp indicating when the default username was last changed.
1805
1806 =attr color
1807
1808 A color associated with the database (in the form C<#ffffff> where "f" is a hexidecimal digit). Some agents
1809 use this to help users visually distinguish between different databases.
1810
1811 =attr master_key_changed
1812
1813 Timestamp indicating when the master key was last changed.
1814
1815 =attr master_key_change_rec
1816
1817 Number of days until the agent should prompt to recommend changing the master key.
1818
1819 =attr master_key_change_force
1820
1821 Number of days until the agent should prompt to force changing the master key.
1822
1823 Note: This is purely advisory. It is up to the individual agent software to actually enforce it.
1824 C<File::KDBX> does NOT enforce it.
1825
1826 =attr custom_icons
1827
1828 Array of custom icons that can be associated with groups and entries.
1829
1830 This list can be managed with the methods L</add_custom_icon> and L</remove_custom_icon>.
1831
1832 =attr recycle_bin_enabled
1833
1834 Boolean indicating whether removed groups and entries should go to a recycle bin or be immediately deleted.
1835
1836 =attr recycle_bin_uuid
1837
1838 The UUID of a group used to store thrown-away groups and entries.
1839
1840 =attr recycle_bin_changed
1841
1842 Timestamp indicating when the recycle bin group was last changed.
1843
1844 =attr entry_templates_group
1845
1846 The UUID of a group containing template entries used when creating new entries.
1847
1848 =attr entry_templates_group_changed
1849
1850 Timestamp indicating when the entry templates group was last changed.
1851
1852 =attr last_selected_group
1853
1854 The UUID of the previously-selected group.
1855
1856 =attr last_top_visible_group
1857
1858 The UUID of the group visible at the top of the list.
1859
1860 =attr history_max_items
1861
1862 The maximum number of historical entries that should be kept for each entry. Default is 10.
1863
1864 =attr history_max_size
1865
1866 The maximum total size (in bytes) that each individual entry's history is allowed to grow. Default is 6 MiB.
1867
1868 =attr maintenance_history_days
1869
1870 The maximum age (in days) historical entries should be kept. Default it 365.
1871
1872 =attr settings_changed
1873
1874 Timestamp indicating when the database settings were last updated.
1875
1876 =attr protect_title
1877
1878 Alias of the L</memory_protection> setting for the I<Title> string.
1879
1880 =attr protect_username
1881
1882 Alias of the L</memory_protection> setting for the I<UserName> string.
1883
1884 =attr protect_password
1885
1886 Alias of the L</memory_protection> setting for the I<Password> string.
1887
1888 =attr protect_url
1889
1890 Alias of the L</memory_protection> setting for the I<URL> string.
1891
1892 =attr protect_notes
1893
1894 Alias of the L</memory_protection> setting for the I<Notes> string.
1895
1896 =cut
1897
1898 #########################################################################################
1899
1900 sub TO_JSON { +{%{$_[0]}} }
1901
1902 1;
1903 __END__
1904
1905 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
1906
1907 =head1 SYNOPSIS
1908
1909 use File::KDBX;
1910
1911 my $kdbx = File::KDBX->new;
1912
1913 my $group = $kdbx->add_group(
1914 name => 'Passwords',
1915 );
1916
1917 my $entry = $group->add_entry(
1918 title => 'My Bank',
1919 password => 's3cr3t',
1920 );
1921
1922 $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
1923
1924 $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
1925
1926 $kdbx->entries->each(sub {
1927 my ($entry) = @_;
1928 say 'Entry: ', $entry->title;
1929 });
1930
1931 See L</RECIPES> for more examples.
1932
1933 =head1 DESCRIPTION
1934
1935 B<File::KDBX> provides everything you need to work with KDBX databases. A KDBX database is a hierarchical
1936 object database which is commonly used to store secret information securely. It was developed for the KeePass
1937 password safe. See L</"Introduction to KDBX"> for more information about KDBX.
1938
1939 This module lets you query entries, create new entries, delete entries, modify entries and more. The
1940 distribution also includes various parsers and generators for serializing and persisting databases.
1941
1942 The design of this software was influenced by the L<KeePassXC|https://github.com/keepassxreboot/keepassxc>
1943 implementation of KeePass as well as the L<File::KeePass> module. B<File::KeePass> is an alternative module
1944 that works well in most cases but has a small backlog of bugs and security issues and also does not work with
1945 newer KDBX version 4 files. If you're coming here from the B<File::KeePass> world, you might be interested in
1946 L<File::KeePass::KDBX> that is a drop-in replacement for B<File::KeePass> that uses B<File::KDBX> for storage.
1947
1948 This software is a B<pre-1.0 release>. The interface should be considered pretty stable, but there might be
1949 minor changes up until a 1.0 release. Breaking changes will be noted in the F<Changes> file.
1950
1951 =head2 Features
1952
1953 =for :list
1954 * ☑ Read and write KDBX version 3 - version 4.1
1955 * ☑ Read and write KDB files (requires L<File::KeePass>)
1956 * ☑ Unicode character strings
1957 * ☑ L</"Simple Expression"> Searching
1958 * ☑ L<Placeholders|File::KDBX::Entry/Placeholders> and L<field references|/resolve_reference>
1959 * ☑ L<One-time passwords|File::KDBX::Entry/"One-time Passwords">
1960 * ☑ L<Very secure|/SECURITY>
1961 * ☑ L</"Memory Protection">
1962 * ☑ Challenge-response key components, like L<YubiKey|File::KDBX::Key::YubiKey>
1963 * ☑ Variety of L<key file|File::KDBX::Key::File> types: binary, hexed, hashed, XML v1 and v2
1964 * ☑ Pluggable registration of different kinds of ciphers and key derivation functions
1965 * ☑ Built-in database maintenance functions
1966 * ☑ Pretty fast, with L<XS optimizations|File::KDBX::XS> available
1967 * ☒ Database synchronization / merging (not yet)
1968
1969 =head2 Introduction to KDBX
1970
1971 A KDBX database consists of a tree of I<groups> and I<entries>, with a single I<root> group. Entries can
1972 contain zero or more key-value pairs of I<strings> and zero or more I<binaries> (i.e. octet strings). Groups,
1973 entries, strings and binaries: that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is
1974 associated with each entry, group and the database as a whole.
1975
1976 You can think of a KDBX database kind of like a file system, where groups are directories, entries are files,
1977 and strings and binaries make up a file's contents.
1978
1979 Databases are typically persisted as encrypted, compressed files. They are usually accessed directly (i.e.
1980 not over a network). The primary focus of this type of database is data security. It is ideal for storing
1981 relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as
1982 have the correct I<master key>. Even if the database file were to be "leaked" to the public Internet, it
1983 should be virtually impossible to crack with a strong key. The KDBX format is most often used by password
1984 managers to store passwords so that users can know a single strong password and not have to reuse passwords
1985 across different websites. See L</SECURITY> for an overview of security considerations.
1986
1987 =head1 RECIPES
1988
1989 =head2 Create a new database
1990
1991 my $kdbx = File::KDBX->new;
1992
1993 my $group = $kdbx->add_group(name => 'Passwords);
1994 my $entry = $group->add_entry(
1995 title => 'WayneCorp',
1996 username => 'bwayne',
1997 password => 'iambatman',
1998 url => 'https://example.com/login'
1999 );
2000 $entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');
2001
2002 $kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');
2003
2004 =head2 Read an existing database
2005
2006 my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
2007 $kdbx->unlock; # cause $entry->password below to be defined
2008
2009 $kdbx->entries->each(sub {
2010 my ($entry) = @_;
2011 say 'Found password for: ', $entry->title;
2012 say ' Username: ', $entry->username;
2013 say ' Password: ', $entry->password;
2014 });
2015
2016 =head2 Search for entries
2017
2018 my @entries = $kdbx->entries(searching => 1)
2019 ->grep(title => 'WayneCorp')
2020 ->each; # return all matches
2021
2022 The C<searching> option limits results to only entries within groups with searching enabled. Other options are
2023 also available. See L</entries>.
2024
2025 See L</QUERY> for many more query examples.
2026
2027 =head2 Search for entries by auto-type window association
2028
2029 my $window_title = 'WayneCorp - Mozilla Firefox';
2030
2031 my $entries = $kdbx->entries(auto_type => 1)
2032 ->filter(sub {
2033 my ($ata) = grep { $_->{window} =~ /\Q$window_title\E/i } @{$_->auto_type_associations};
2034 return [$_, $ata->{keystroke_sequence}] if $ata;
2035 })
2036 ->each(sub {
2037 my ($entry, $keys) = @$_;
2038 say 'Entry title: ', $entry->title, ', key sequence: ', $keys;
2039 });
2040
2041 Example output:
2042
2043 Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}
2044
2045 =head2 Remove entries from a database
2046
2047 $kdbx->entries
2048 ->grep(notes => {'=~' => qr/too old/i})
2049 ->each(sub { $_->recycle });
2050
2051 Recycle all entries with the string "too old" appearing in the B<Notes> string.
2052
2053 =head2 Remove empty groups
2054
2055 $kdbx->groups(algorithm => 'dfs')
2056 ->where(-true => 'is_empty')
2057 ->each('remove');
2058
2059 With the search/iteration C<algorithm> set to "dfs", groups will be ordered deepest first and the root group
2060 will be last. This allows removing groups that only contain empty groups.
2061
2062 This can also be done with one call to L</remove_empty_groups>.
2063
2064 =head1 SECURITY
2065
2066 One of the biggest threats to your database security is how easily the encryption key can be brute-forced.
2067 Strong brute-force protection depends on:
2068
2069 =for :list
2070 * Using unguessable passwords, passphrases and key files.
2071 * Using a brute-force resistent key derivation function.
2072
2073 The first factor is up to you. This module does not enforce strong master keys. It is up to you to pick or
2074 generate strong keys.
2075
2076 The KDBX format allows for the key derivation function to be tuned. The idea is that you want each single
2077 brute-foce attempt to be expensive (in terms of time, CPU usage or memory usage), so that making a lot of
2078 attempts (which would be required if you have a strong master key) gets I<really> expensive.
2079
2080 How expensive you want to make each attempt is up to you and can depend on the application.
2081
2082 This and other KDBX-related security issues are covered here more in depth:
2083 L<https://keepass.info/help/base/security.html>
2084
2085 Here are other security risks you should be thinking about:
2086
2087 =head2 Cryptography
2088
2089 This distribution uses the excellent L<CryptX> and L<Crypt::Argon2> packages to handle all crypto-related
2090 functions. As such, a lot of the security depends on the quality of these dependencies. Fortunately these
2091 modules are maintained and appear to have good track records.
2092
2093 The KDBX format has evolved over time to incorporate improved security practices and cryptographic functions.
2094 This package uses the following functions for authentication, hashing, encryption and random number
2095 generation:
2096
2097 =for :list
2098 * AES-128 (legacy)
2099 * AES-256
2100 * Argon2d & Argon2id
2101 * CBC block mode
2102 * HMAC-SHA256
2103 * SHA256
2104 * SHA512
2105 * Salsa20 & ChaCha20
2106 * Twofish
2107
2108 At the time of this writing, I am not aware of any successful attacks against any of these functions. These
2109 are among the most-analyzed and widely-adopted crypto functions available.
2110
2111 The KDBX format allows the body cipher and key derivation function to be configured. If a flaw is discovered
2112 in one of these functions, you can hopefully just switch to a better function without needing to update this
2113 software. A later software release may phase out the use of any functions which are no longer secure.
2114
2115 =head2 Memory Protection
2116
2117 It is not a good idea to keep secret information unencrypted in system memory for longer than is needed. The
2118 address space of your program can generally be read by a user with elevated privileges on the system. If your
2119 system is memory-constrained or goes into a hibernation mode, the contents of your address space could be
2120 written to a disk where it might be persisted for long time.
2121
2122 There might be system-level things you can do to reduce your risk, like using swap encryption and limiting
2123 system access to your program's address space while your program is running.
2124
2125 B<File::KDBX> helps minimize (but not eliminate) risk by keeping secrets encrypted in memory until accessed
2126 and zeroing out memory that holds secrets after they're no longer needed, but it's not a silver bullet.
2127
2128 For one thing, the encryption key is stored in the same address space. If core is dumped, the encryption key
2129 is available to be found out. But at least there is the chance that the encryption key and the encrypted
2130 secrets won't both be paged out together while memory-constrained.
2131
2132 Another problem is that some perls (somewhat notoriously) copy around memory behind the scenes willy nilly,
2133 and it's difficult know when perl makes a copy of a secret in order to be able to zero it out later. It might
2134 be impossible. The good news is that perls with SvPV copy-on-write (enabled by default beginning with perl
2135 5.20) are much better in this regard. With COW, it's mostly possible to know what operations will cause perl
2136 to copy the memory of a scalar string, and the number of copies will be significantly reduced. There is a unit
2137 test named F<t/memory-protection.t> in this distribution that can be run on POSIX systems to determine how
2138 well B<File::KDBX> memory protection is working.
2139
2140 Memory protection also depends on how your application handles secrets. If your app code is handling scalar
2141 strings with secret information, it's up to you to make sure its memory is zeroed out when no longer needed.
2142 L<File::KDBX::Util/erase> et al. provide some tools to help accomplish this. Or if you're not too concerned
2143 about the risks memory protection is meant to mitigate, then maybe don't worry about it. The security policy
2144 of B<File::KDBX> is to try hard to keep secrets protected while in memory so that your app might claim a high
2145 level of security, in case you care about that.
2146
2147 There are some memory protection strategies that B<File::KDBX> does NOT use today but could in the future:
2148
2149 Many systems allow programs to mark unswappable pages. Secret information should ideally be stored in such
2150 pages. You could potentially use L<mlockall(2)> (or equivalent for your system) in your own application to
2151 prevent the entire address space from being swapped.
2152
2153 Some systems provide special syscalls for storing secrets in memory while keeping the encryption key outside
2154 of the program's address space, like C<CryptProtectMemory> for Windows. This could be a good option, though
2155 unfortunately not portable.
2156
2157 =head1 QUERY
2158
2159 To find things in a KDBX database, you should use a filtered iterator. If you have an iterator, such as
2160 returned by L</entries>, L</groups> or even L</objects> you can filter it using L<File::KDBX::Iterator/where>.
2161
2162 my $filtered_entries = $kdbx->entries->where(\&query);
2163
2164 A C<\&query> is just a subroutine that you can either write yourself or have generated for you from either
2165 a L</"Simple Expression"> or L</"Declarative Syntax">. It's easier to have your query generated, so I'll cover
2166 that first.
2167
2168 =head2 Simple Expression
2169
2170 A simple expression is mostly compatible with the KeePass 2 implementation
2171 L<described here|https://keepass.info/help/base/search.html#mode_se>.
2172
2173 An expression is a string with one or more space-separated terms. Terms with spaces can be enclosed in double
2174 quotes. Terms are negated if they are prefixed with a minus sign. A record must match every term on at least
2175 one of the given fields.
2176
2177 So a simple expression is something like what you might type into a search engine. You can generate a simple
2178 expression query using L<File::KDBX::Util/simple_expression_query> or by passing the simple expression as
2179 a B<scalar reference> to C<where>.
2180
2181 To search for all entries in a database with the word "canyon" appearing anywhere in the title:
2182
2183 my $entries = $kdbx->entries->where(\'canyon', qw[title]);
2184
2185 Notice the first argument is a B<scalarref>. This disambiguates a simple expression from other types of
2186 queries covered below.
2187
2188 As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that
2189 has the words "red" B<and> "canyon" anywhere in the title:
2190
2191 my $entries = $kdbx->entries->where(\'red canyon', qw[title]);
2192
2193 Each term in the simple expression must be found for an entry to match.
2194
2195 To search for entries with "red" in the title but B<not> "canyon", just prepend "canyon" with a minus sign:
2196
2197 my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);
2198
2199 To search over multiple fields simultaneously, just list them all. To search for entries with "grocery" (but
2200 not "Foodland") in the title or notes:
2201
2202 my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);
2203
2204 The default operator is a case-insensitive regexp match, which is fine for searching text loosely. You can use
2205 just about any binary comparison operator that perl supports. To specify an operator, list it after the simple
2206 expression. For example, to search for any entry that has been used at least five times:
2207
2208 my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);
2209
2210 It helps to read it right-to-left, like "usage_count is greater than or equal to 5".
2211
2212 If you find the disambiguating structures to be distracting or confusing, you can also the
2213 L<File::KDBX::Util/simple_expression_query> function as a more intuitive alternative. The following example is
2214 equivalent to the previous:
2215
2216 my $entries = $kdbx->entries->where(simple_expression_query(5, '>=', qw[usage_count]));
2217
2218 =head2 Declarative Syntax
2219
2220 Structuring a declarative query is similar to L<SQL::Abstract/"WHERE CLAUSES">, but you don't have to be
2221 familiar with that module. Just learn by examples here.
2222
2223 To search for all entries in a database titled "My Bank":
2224
2225 my $entries = $kdbx->entries->where({ title => 'My Bank' });
2226
2227 The query here is C<< { title => 'My Bank' } >>. A hashref can contain key-value pairs where the key is an
2228 attribute of the thing being searched for (in this case an entry) and the value is what you want the thing's
2229 attribute to be to consider it a match. In this case, the attribute we're using as our match criteria is
2230 L<File::KDBX::Entry/title>, a text field. If an entry has its title attribute equal to "My Bank", it's
2231 a match.
2232
2233 A hashref can contain multiple attributes. The search candidate will be a match if I<all> of the specified
2234 attributes are equal to their respective values. For example, to search for all entries with a particular URL
2235 B<AND> username:
2236
2237 my $entries = $kdbx->entries->where({
2238 url => 'https://example.com',
2239 username => 'neo',
2240 });
2241
2242 To search for entries matching I<any> criteria, just change the hashref to an arrayref. To search for entries
2243 with a particular URL B<OR> username:
2244
2245 my $entries = $kdbx->entries->where([ # <-- Notice the square bracket
2246 url => 'https://example.com',
2247 username => 'neo',
2248 ]);
2249
2250 You can use different operators to test different types of attributes. The L<File::KDBX::Entry/icon_id>
2251 attribute is a number, so we should use a number comparison operator. To find entries using the smartphone
2252 icon:
2253
2254 my $entries = $kdbx->entries->where({
2255 icon_id => { '==', ICON_SMARTPHONE },
2256 });
2257
2258 Note: L<File::KDBX::Constants/ICON_SMARTPHONE> is just a constant from L<File::KDBX::Constants>. It isn't
2259 special to this example or to queries generally. We could have just used a literal number.
2260
2261 The important thing to notice here is how we wrapped the condition in another arrayref with a single key-value
2262 pair where the key is the name of an operator and the value is the thing to match against. The supported
2263 operators are:
2264
2265 =for :list
2266 * C<eq> - String equal
2267 * C<ne> - String not equal
2268 * C<lt> - String less than
2269 * C<gt> - String greater than
2270 * C<le> - String less than or equal
2271 * C<ge> - String greater than or equal
2272 * C<==> - Number equal
2273 * C<!=> - Number not equal
2274 * C<< < >> - Number less than
2275 * C<< > >> - Number greater than
2276 * C<< <= >> - Number less than or equal
2277 * C<< >= >> - Number less than or equal
2278 * C<=~> - String match regular expression
2279 * C<!~> - String does not match regular expression
2280 * C<!> - Boolean false
2281 * C<!!> - Boolean true
2282
2283 Other special operators:
2284
2285 =for :list
2286 * C<-true> - Boolean true
2287 * C<-false> - Boolean false
2288 * C<-not> - Boolean false (alias for C<-false>)
2289 * C<-defined> - Is defined
2290 * C<-undef> - Is not defined
2291 * C<-empty> - Is empty
2292 * C<-nonempty> - Is not empty
2293 * C<-or> - Logical or
2294 * C<-and> - Logical and
2295
2296 Let's see another example using an explicit operator. To find all groups except one in particular (identified
2297 by its L<File::KDBX::Group/uuid>), we can use the C<ne> (string not equal) operator:
2298
2299 my $groups = $kdbx->groups->where(
2300 uuid => {
2301 'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
2302 },
2303 );
2304
2305 Note: L<File::KDBX::Util/uuid> is a little utility function to convert a UUID in its pretty form into bytes.
2306 This utility function isn't special to this example or to queries generally. It could have been written with
2307 a literal such as C<"\x59\x6f\x75\x20\x61...">, but that's harder to read.
2308
2309 Notice we searched for groups this time. Finding groups works exactly the same as it does for entries.
2310
2311 Notice also that we didn't wrap the query in hashref curly-braces or arrayref square-braces. Those are
2312 optional. By default it will only match ALL attributes (as if there were curly-braces).
2313
2314 Testing the truthiness of an attribute is a little bit different because it isn't a binary operation. To find
2315 all entries with the password quality check disabled:
2316
2317 my $entries = $kdbx->entries->where('!' => 'quality_check');
2318
2319 This time the string after the operator is the attribute name rather than a value to compare the attribute
2320 against. To test that a boolean value is true, use the C<!!> operator (or C<-true> if C<!!> seems a little too
2321 weird for your taste):
2322
2323 my $entries = $kdbx->entries->where('!!' => 'quality_check');
2324 my $entries = $kdbx->entries->where(-true => 'quality_check'); # same thing
2325
2326 Yes, there is also a C<-false> and a C<-not> if you prefer one of those over C<!>. C<-false> and C<-not>
2327 (along with C<-true>) are also special in that you can use them to invert the logic of a subquery. These are
2328 logically equivalent:
2329
2330 my $entries = $kdbx->entries->where(-not => { title => 'My Bank' });
2331 my $entries = $kdbx->entries->where(title => { 'ne' => 'My Bank' });
2332
2333 These special operators become more useful when combined with two more special operators: C<-and> and C<-or>.
2334 With these, it is possible to construct more interesting queries with groups of logic. For example:
2335
2336 my $entries = $kdbx->entries->where({
2337 title => { '=~', qr/bank/ },
2338 -not => {
2339 -or => {
2340 notes => { '=~', qr/business/ },
2341 icon_id => { '==', ICON_TRASHCAN_FULL },
2342 },
2343 },
2344 });
2345
2346 In English, find entries where the word "bank" appears anywhere in the title but also do not have either the
2347 word "business" in the notes or are using the full trashcan icon.
2348
2349 =head2 Subroutine Query
2350
2351 Lastly, as mentioned at the top, you can ignore all this and write your own subroutine. Your subroutine will
2352 be called once for each object being searched over. The subroutine should match the candidate against whatever
2353 criteria you want and return true if it matches or false to skip. To do this, just pass your subroutine
2354 coderef to C<where>.
2355
2356 To review the different types of queries, these are all equivalent to find all entries in the database titled
2357 "My Bank":
2358
2359 my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]); # simple expression
2360 my $entries = $kdbx->entries->where(title => 'My Bank'); # declarative syntax
2361 my $entries = $kdbx->entries->where(sub { $_->title eq 'My Bank' }); # subroutine query
2362
2363 This is a trivial example, but of course your subroutine can be arbitrarily complex.
2364
2365 All of these query mechanisms described in this section are just tools, each with its own set of limitations.
2366 If the tools are getting in your way, you can of course iterate over the contents of a database and implement
2367 your own query logic, like this:
2368
2369 my $entries = $kdbx->entries;
2370 while (my $entry = $entries->next) {
2371 if (wanted($entry)) {
2372 do_something($entry);
2373 }
2374 else {
2375 ...
2376 }
2377 }
2378
2379 =head2 Iteration
2380
2381 Iterators are the built-in way to navigate or walk the database tree. You get an iterator from L</entries>,
2382 L</groups> and L</objects>. You can specify the search algorithm to iterate over objects in different orders
2383 using the C<algorith> option, which can be one of these L<constants|File::KDBX::Constants/":iteration">:
2384
2385 =for :list
2386 * C<ITERATION_IDS> - Iterative deepening search (default)
2387 * C<ITERATION_DFS> - Depth-first search
2388 * C<ITERATION_BFS> - Breadth-first search
2389
2390 When iterating over objects generically, groups always precede their direct entries (if any). When the
2391 C<history> option is used, current entries always precede historical entries.
2392
2393 If you have a database tree like this:
2394
2395 Database
2396 - Root
2397 - Group1
2398 - EntryA
2399 - Group2
2400 - EntryB
2401 - Group3
2402 - EntryC
2403
2404 =for :list
2405 * IDS order of groups is: Root, Group1, Group2, Group3
2406 * IDS order of entries is: EntryA, EntryB, EntryC
2407 * IDS order of objects is: Root, Group1, EntryA, Group2, EntryB, Group3, EntryC
2408 * DFS order of groups is: Group2, Group1, Group3, Root
2409 * DFS order of entries is: EntryB, EntryA, EntryC
2410 * DFS order of objects is: Group2, EntryB, Group1, EntryA, Group3, EntryC, Root
2411 * BFS order of groups is: Root, Group1, Group3, Group2
2412 * BFS order of entries is: EntryA, EntryC, EntryB
2413 * BFS order of objects is: Root, Group1, EntryA, Group3, EntryC, Group2, EntryB
2414
2415 =head1 SYNCHRONIZING
2416
2417 B<TODO> - This is a planned feature, not yet implemented.
2418
2419 =head1 ERRORS
2420
2421 Errors in this package are constructed as L<File::KDBX::Error> objects and propagated using perl's built-in
2422 mechanisms. Fatal errors are propagated using L<perlfunc/"die LIST"> and non-fatal errors (a.k.a. warnings)
2423 are propagated using L<perlfunc/"warn LIST"> while adhering to perl's L<warnings> system. If you're already
2424 familiar with these mechanisms, you can skip this section.
2425
2426 You can catch fatal errors using L<perlfunc/"eval BLOCK"> (or something like L<Try::Tiny>) and non-fatal
2427 errors using C<$SIG{__WARN__}> (see L<perlvar/%SIG>). Examples:
2428
2429 use File::KDBX::Error qw(error);
2430
2431 my $key = ''; # uh oh
2432 eval {
2433 $kdbx->load_file('whatever.kdbx', $key);
2434 };
2435 if (my $error = error($@)) {
2436 handle_missing_key($error) if $error->type eq 'key.missing';
2437 $error->throw;
2438 }
2439
2440 or using C<Try::Tiny>:
2441
2442 try {
2443 $kdbx->load_file('whatever.kdbx', $key);
2444 }
2445 catch {
2446 handle_error($_);
2447 };
2448
2449 Catching non-fatal errors:
2450
2451 my @warnings;
2452 local $SIG{__WARN__} = sub { push @warnings, $_[0] };
2453
2454 $kdbx->load_file('whatever.kdbx', $key);
2455
2456 handle_warnings(@warnings) if @warnings;
2457
2458 By default perl prints warnings to C<STDERR> if you don't catch them. If you don't want to catch them and also
2459 don't want them printed to C<STDERR>, you can suppress them lexically (perl v5.28 or higher required):
2460
2461 {
2462 no warnings 'File::KDBX';
2463 ...
2464 }
2465
2466 or locally:
2467
2468 {
2469 local $File::KDBX::WARNINGS = 0;
2470 ...
2471 }
2472
2473 or globally in your program:
2474
2475 $File::KDBX::WARNINGS = 0;
2476
2477 You cannot suppress fatal errors, and if you don't catch them your program will exit.
2478
2479 =head1 ENVIRONMENT
2480
2481 This software will alter its behavior depending on the value of certain environment variables:
2482
2483 =for :list
2484 * C<PERL_FILE_KDBX_XS> - Do not use L<File::KDBX::XS> if false (default: true)
2485 * C<PERL_ONLY> - Do not use L<File::KDBX::XS> if true (default: false)
2486 * C<NO_FORK> - Do not fork if true (default: false)
2487
2488 =head1 CAVEATS
2489
2490 Some features (e.g. parsing) require 64-bit perl. It should be possible and actually pretty easy to make it
2491 work using L<Math::BigInt>, but I need to build a 32-bit perl in order to test it and frankly I'm still
2492 figuring out how. I'm sure it's simple so I'll mark this one "TODO", but for now an exception will be thrown
2493 when trying to use such features with undersized IVs.
2494
2495 =head1 SEE ALSO
2496
2497 =for :list
2498 * L<KeePass Password Safe|https://keepass.info/> - The original KeePass
2499 * L<KeePassXC|https://keepassxc.org/> - Cross-Platform Password Manager written in C++
2500 * L<File::KeePass> has overlapping functionality. It's good but has a backlog of some pretty critical bugs and
2501 lacks support for newer KDBX features.
2502
2503 =begin :header
2504
2505 =begin markdown
2506
2507 [![Linux](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml/badge.svg)](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml)
2508 [![macOS](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml/badge.svg)](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml)
2509 [![Windows](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml/badge.svg)](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml)
2510
2511 =end markdown
2512
2513 =begin HTML
2514
2515 <a title="Linux" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml/badge.svg"></a>
2516 <a title="macOS" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml/badge.svg"></a>
2517 <a title="Windows" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml/badge.svg"></a>
2518
2519 =end HTML
2520
2521 =end :header
2522
2523 =cut
This page took 0.211407 seconds and 3 git commands to generate.