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