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

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