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