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

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