Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX.pm

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