2 # ABSTRACT: Encrypted database to store secret text and files
8 use Crypt
::Digest
qw(digest_data);
9 use Crypt
::PRNG
qw(random_bytes);
10 use Devel
::GlobalDestruction
;
11 use File
::KDBX
::Constants
qw(:all :icon);
12 use File
::KDBX
::Error
;
14 use File
::KDBX
::Util
qw(:class :coercion :empty :search :uuid erase simple_expression_query snakify);
15 use Hash
::Util
::FieldHash
qw(fieldhashes);
16 use List
::Util
qw(any first);
17 use Ref
::Util
qw(is_ref is_arrayref is_plain_hashref);
18 use Scalar
::Util
qw(blessed);
23 our $VERSION = '0.903'; # VERSION
26 fieldhashes \
my (%SAFE, %KEYS);
33 return $_[0]->clone if @_ == 1 && blessed
$_[0] && $_[0]->isa($class);
35 my $self = bless {}, $class;
37 $self->_set_nonlazy_attributes if empty
$self;
41 sub DESTROY
{ local ($., $@, $!, $^E, $?); !in_global_destruction
and $_[0]->reset }
48 @$self{keys %args} = values %args;
56 erase
$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY
};
57 erase
$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY
};
68 return Storable
::dclone
($self);
77 return '', $copy, $KEYS{$self} // (), $SAFE{$self} // ();
88 @$self{keys %$clone} = values %$clone;
92 # Dualvars aren't cloned as dualvars, so coerce the compression flags.
93 $self->compression_flags($self->compression_flags);
95 $self->objects(history
=> 1)->each(sub { $_->kdbx($self) });
98 ##############################################################################
101 sub load
{ shift-
>_loader->load(@_) }
102 sub load_string
{ shift-
>_loader->load_string(@_) }
103 sub load_file
{ shift-
>_loader->load_file(@_) }
104 sub load_handle
{ shift-
>_loader->load_handle(@_) }
108 $self = $self->new if !ref $self;
109 require File
::KDBX
::Loader
;
110 File
::KDBX
::Loader-
>new(kdbx
=> $self);
114 sub dump { shift-
>_dumper->dump(@_) }
115 sub dump_string
{ shift-
>_dumper->dump_string(@_) }
116 sub dump_file
{ shift-
>_dumper->dump_file(@_) }
117 sub dump_handle
{ shift-
>_dumper->dump_handle(@_) }
121 $self = $self->new if !ref $self;
122 require File
::KDBX
::Dumper
;
123 File
::KDBX
::Dumper-
>new(kdbx
=> $self);
126 ##############################################################################
129 sub user_agent_string
{
131 sprintf('%s/%s (%s/%s; %s/%s; %s)',
132 __PACKAGE__
, $VERSION, @Config::Config
{qw(package version osname osvers archname)});
135 has sig1
=> KDBX_SIG1
, coerce
=> \
&to_number
;
136 has sig2
=> KDBX_SIG2_2
, coerce
=> \
&to_number
;
137 has version
=> KDBX_VERSION_3_1
, coerce
=> \
&to_number
;
139 has inner_headers
=> {};
142 has deleted_objects
=> {};
143 has raw
=> coerce
=> \
&to_string
;
146 has 'headers.comment' => '', coerce
=> \
&to_string
;
147 has 'headers.cipher_id' => CIPHER_UUID_CHACHA20
, coerce
=> \
&to_uuid
;
148 has 'headers.compression_flags' => COMPRESSION_GZIP
, coerce
=> \
&to_compression_constant
;
149 has 'headers.master_seed' => sub { random_bytes
(32) }, coerce
=> \
&to_string
;
150 has 'headers.encryption_iv' => sub { random_bytes
(16) }, coerce
=> \
&to_string
;
151 has 'headers.stream_start_bytes' => sub { random_bytes
(32) }, coerce
=> \
&to_string
;
152 has 'headers.kdf_parameters' => sub {
154 KDF_PARAM_UUID
() => KDF_UUID_AES
,
155 KDF_PARAM_AES_ROUNDS
() => $_[0]->headers->{+HEADER_TRANSFORM_ROUNDS
} // KDF_DEFAULT_AES_ROUNDS
,
156 KDF_PARAM_AES_SEED
() => $_[0]->headers->{+HEADER_TRANSFORM_SEED
} // random_bytes
(32),
159 # has 'headers.transform_seed' => sub { random_bytes(32) };
160 # has 'headers.transform_rounds' => 100_000;
161 # has 'headers.inner_random_stream_key' => sub { random_bytes(32) }; # 64 ?
162 # has 'headers.inner_random_stream_id' => STREAM_ID_CHACHA20;
163 # has 'headers.public_custom_data' => {};
166 has 'meta.generator' => '', coerce
=> \
&to_string
;
167 has 'meta.header_hash' => '', coerce
=> \
&to_string
;
168 has 'meta.database_name' => '', coerce
=> \
&to_string
;
169 has 'meta.database_name_changed' => sub { gmtime }, coerce
=> \
&to_time
;
170 has 'meta.database_description' => '', coerce
=> \
&to_string
;
171 has 'meta.database_description_changed' => sub { gmtime }, coerce
=> \
&to_time
;
172 has 'meta.default_username' => '', coerce
=> \
&to_string
;
173 has 'meta.default_username_changed' => sub { gmtime }, coerce
=> \
&to_time
;
174 has 'meta.maintenance_history_days' => HISTORY_DEFAULT_MAX_AGE
, coerce
=> \
&to_number
;
175 has 'meta.color' => '', coerce
=> \
&to_string
;
176 has 'meta.master_key_changed' => sub { gmtime }, coerce
=> \
&to_time
;
177 has 'meta.master_key_change_rec' => -1, coerce
=> \
&to_number
;
178 has 'meta.master_key_change_force' => -1, coerce
=> \
&to_number
;
179 # has 'meta.memory_protection' => {};
180 has 'meta.custom_icons' => [];
181 has 'meta.recycle_bin_enabled' => true
, coerce
=> \
&to_bool
;
182 has 'meta.recycle_bin_uuid' => UUID_NULL
, coerce
=> \
&to_uuid
;
183 has 'meta.recycle_bin_changed' => sub { gmtime }, coerce
=> \
&to_time
;
184 has 'meta.entry_templates_group' => UUID_NULL
, coerce
=> \
&to_uuid
;
185 has 'meta.entry_templates_group_changed' => sub { gmtime }, coerce
=> \
&to_time
;
186 has 'meta.last_selected_group' => UUID_NULL
, coerce
=> \
&to_uuid
;
187 has 'meta.last_top_visible_group' => UUID_NULL
, coerce
=> \
&to_uuid
;
188 has 'meta.history_max_items' => HISTORY_DEFAULT_MAX_ITEMS
, coerce
=> \
&to_number
;
189 has 'meta.history_max_size' => HISTORY_DEFAULT_MAX_SIZE
, coerce
=> \
&to_number
;
190 has 'meta.settings_changed' => sub { gmtime }, coerce
=> \
&to_time
;
191 # has 'meta.binaries' => {};
192 # has 'meta.custom_data' => {};
194 has 'memory_protection.protect_title' => false
, coerce
=> \
&to_bool
;
195 has 'memory_protection.protect_username' => false
, coerce
=> \
&to_bool
;
196 has 'memory_protection.protect_password' => true
, coerce
=> \
&to_bool
;
197 has 'memory_protection.protect_url' => false
, coerce
=> \
&to_bool
;
198 has 'memory_protection.protect_notes' => false
, coerce
=> \
&to_bool
;
199 # has 'memory_protection.auto_enable_visual_hiding' => false;
202 HEADER_TRANSFORM_SEED
,
203 HEADER_TRANSFORM_ROUNDS
,
204 HEADER_INNER_RANDOM_STREAM_KEY
,
205 HEADER_INNER_RANDOM_STREAM_ID
,
206 HEADER_PUBLIC_CUSTOM_DATA
,
208 sub _set_nonlazy_attributes
{
210 $self->$_ for list_attributes
(ref $self), @ATTRS;
214 sub memory_protection
{
216 $self->{meta
}{memory_protection
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
217 return $self->{meta
}{memory_protection
} //= {} if !@_;
219 my $string_key = shift;
220 my $key = 'protect_' . lc($string_key);
222 $self->meta->{memory_protection
}{$key} = shift if @_;
223 $self->meta->{memory_protection
}{$key};
227 sub minimum_version
{
230 return KDBX_VERSION_4_1
if any
{
231 nonempty
$_->{last_modification_time
}
232 } values %{$self->custom_data};
234 return KDBX_VERSION_4_1
if any
{
235 nonempty
$_->{name
} || nonempty
$_->{last_modification_time
}
236 } @{$self->custom_icons};
238 return KDBX_VERSION_4_1
if $self->groups->next(sub {
239 nonempty
$_->previous_parent_group ||
241 (any
{ nonempty
$_->{last_modification_time
} } values %{$_->custom_data})
244 return KDBX_VERSION_4_1
if $self->entries(history
=> 1)->next(sub {
245 nonempty
$_->previous_parent_group ||
246 (defined $_->quality_check && !$_->quality_check) ||
247 (any
{ nonempty
$_->{last_modification_time
} } values %{$_->custom_data})
250 return KDBX_VERSION_4_0
if $self->kdf->uuid ne KDF_UUID_AES
;
252 return KDBX_VERSION_4_0
if nonempty
$self->public_custom_data;
254 return KDBX_VERSION_4_0
if $self->objects->next(sub {
255 nonempty
$_->custom_data
258 return KDBX_VERSION_3_1
;
261 ##############################################################################
267 $self->{root
} = $self->_wrap_group(@_);
268 $self->{root
}->kdbx($self);
270 $self->{root
} //= $self->_implicit_root;
271 return $self->_wrap_group($self->{root
});
274 # Called by File::KeePass::KDBX so that a File::KDBX an be treated as a File::KDBX::Group in that both types
275 # can have subgroups. File::KDBX already has a `groups' method that does something different from the
276 # File::KDBX::Groups `groups' method.
279 return [] if !$self->{root
};
280 return $self->_has_implicit_root ? $self->root->groups : [$self->root];
283 sub _has_implicit_root
{
285 my $root = $self->root;
286 my $temp = __PACKAGE__-
>_implicit_root;
287 # If an implicit root group has been changed in any significant way, it is no longer implicit.
288 return $root->name eq $temp->name &&
289 $root->is_expanded ^ $temp->is_expanded &&
290 $root->notes eq $temp->notes &&
291 !@{$root->entries} &&
292 !defined $root->custom_icon_uuid &&
293 !keys %{$root->custom_data} &&
294 $root->icon_id == $temp->icon_id &&
295 $root->expires ^ $temp->expires &&
296 $root->default_auto_type_sequence eq $temp->default_auto_type_sequence &&
297 !defined $root->enable_auto_type &&
298 !defined $root->enable_searching;
303 require File
::KDBX
::Group
;
304 return File
::KDBX
::Group-
>new(
307 notes
=> 'Added as an implicit root group by '.__PACKAGE__
.'.',
308 ref $self ? (kdbx
=> $self) : (),
316 return $object->lineage(@_);
324 push @lineage, $self->root if !@lineage;
325 my $base = $lineage[-1] or return [];
327 my $uuid = $object->uuid;
328 return \
@lineage if any
{ $_->uuid eq $uuid } @{$base->groups}, @{$base->entries};
330 for my $subgroup (@{$base->groups}) {
331 my $result = $self->_trace_lineage($object, @lineage, $subgroup);
332 return $result if $result;
339 if (my $group = shift) {
340 $self->recycle_bin_uuid($group->uuid);
344 my $uuid = $self->recycle_bin_uuid;
345 $group = $self->groups->grep(uuid
=> $uuid)->next if $uuid ne UUID_NULL
;
346 if (!$group && $self->recycle_bin_enabled) {
347 $group = $self->add_group(
348 name
=> 'Recycle Bin',
349 icon_id
=> ICON_TRASHCAN_FULL
,
350 enable_auto_type
=> false
,
351 enable_searching
=> false
,
353 $self->recycle_bin_uuid($group->uuid);
359 sub entry_templates
{
361 if (my $group = shift) {
362 $self->entry_templates_group($group->uuid);
365 my $uuid = $self->entry_templates_group;
366 return if $uuid eq UUID_NULL
;
367 return $self->groups->grep(uuid
=> $uuid)->next;
373 if (my $group = shift) {
374 $self->last_selected_group($group->uuid);
377 my $uuid = $self->last_selected_group;
378 return if $uuid eq UUID_NULL
;
379 return $self->groups->grep(uuid
=> $uuid)->next;
383 sub last_top_visible
{
385 if (my $group = shift) {
386 $self->last_top_visible_group($group->uuid);
389 my $uuid = $self->last_top_visible_group;
390 return if $uuid eq UUID_NULL
;
391 return $self->groups->grep(uuid
=> $uuid)->next;
394 ##############################################################################
399 my $group = @_ % 2 == 1 ? shift : undef;
402 # find the right group to add the group to
403 my $parent = delete $args{group
} // $self->root;
404 $parent = $self->groups->grep({uuid
=> $parent})->next if !ref $parent;
405 $parent or throw
'Invalid group';
407 return $parent->add_group(defined $group ? $group : (), %args, kdbx
=> $self);
413 require File
::KDBX
::Group
;
414 return File
::KDBX
::Group-
>wrap($group, $self);
420 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
421 my $base = delete $args{base
} // $self->root;
423 return $base->all_groups(%args);
426 ##############################################################################
431 my $entry = @_ % 2 == 1 ? shift : undef;
434 # find the right group to add the entry to
435 my $parent = delete $args{group
} // $self->root;
436 $parent = $self->groups->grep({uuid
=> $parent})->next if !ref $parent;
437 $parent or throw
'Invalid group';
439 return $parent->add_entry(defined $entry ? $entry : (), %args, kdbx
=> $self);
445 require File
::KDBX
::Entry
;
446 return File
::KDBX
::Entry-
>wrap($entry, $self);
452 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
453 my $base = delete $args{base
} // $self->root;
455 return $base->all_entries(%args);
458 ##############################################################################
463 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
464 my $base = delete $args{base
} // $self->root;
466 return $base->all_objects(%args);
469 sub __iter__
{ $_[0]->objects }
471 ##############################################################################
476 my %args = @_ == 2 ? (uuid
=> shift, data
=> shift)
477 : @_ % 2 == 1 ? (uuid
=> shift, @_) : @_;
479 if (!$args{uuid
} && !$args{data
}) {
480 my %standard = (uuid
=> 1, data
=> 1, name
=> 1, last_modification_time
=> 1);
481 my @other_keys = grep { !$standard{$_} } keys %args;
482 if (@other_keys == 1) {
483 my $key = $args{key
} = $other_keys[0];
484 $args{data
} = delete $args{$key};
488 my $uuid = $args{uuid
} or throw
'Must provide a custom icon UUID to access';
489 my $icon = (first
{ $_->{uuid
} eq $uuid } @{$self->custom_icons}) // do {
490 push @{$self->custom_icons}, my $i = { uuid
=> $uuid };
495 $fields = $args{data
} if is_plain_hashref
($args{data
});
497 while (my ($field, $value) = each %$fields) {
498 $icon->{$field} = $value;
504 sub custom_icon_data
{
506 my $uuid = shift // return;
507 my $icon = first
{ $_->{uuid
} eq $uuid } @{$self->custom_icons} or return;
508 return $icon->{data
};
512 sub add_custom_icon
{
514 my %args = @_ % 2 == 1 ? (data
=> shift, @_) : @_;
516 defined $args{data
} or throw
'Must provide image data';
518 my $uuid = $args{uuid
} // generate_uuid
;
519 push @{$self->custom_icons}, {
528 sub remove_custom_icon
{
532 @{$self->custom_icons} = grep { $_->{uuid
} eq $uuid ? do { push @deleted, $_; 0 } : 1 }
533 @{$self->custom_icons};
534 $self->add_deleted_object($uuid) if @deleted;
538 ##############################################################################
543 $self->{meta
}{custom_data
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
544 return $self->{meta
}{custom_data
} //= {} if !@_;
546 my %args = @_ == 2 ? (key
=> shift, value
=> shift)
547 : @_ % 2 == 1 ? (key
=> shift, @_) : @_;
549 if (!$args{key
} && !$args{value
}) {
550 my %standard = (key
=> 1, value
=> 1, last_modification_time
=> 1);
551 my @other_keys = grep { !$standard{$_} } keys %args;
552 if (@other_keys == 1) {
553 my $key = $args{key
} = $other_keys[0];
554 $args{value
} = delete $args{$key};
558 my $key = $args{key
} or throw
'Must provide a custom_data key to access';
560 return $self->{meta
}{custom_data
}{$key} = $args{value
} if is_plain_hashref
($args{value
});
562 while (my ($field, $value) = each %args) {
563 $self->{meta
}{custom_data
}{$key}{$field} = $value;
565 return $self->{meta
}{custom_data
}{$key};
569 sub custom_data_value
{
571 my $data = $self->custom_data(@_) // return;
572 return $data->{value
};
576 sub public_custom_data
{
578 $self->{headers
}{+HEADER_PUBLIC_CUSTOM_DATA
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
579 return $self->{headers
}{+HEADER_PUBLIC_CUSTOM_DATA
} //= {} if !@_;
581 my $key = shift or throw
'Must provide a public_custom_data key to access';
582 $self->{headers
}{+HEADER_PUBLIC_CUSTOM_DATA
}{$key} = shift if @_;
583 return $self->{headers
}{+HEADER_PUBLIC_CUSTOM_DATA
}{$key};
586 ##############################################################################
593 # my %options = @_; # prefer_old / prefer_new
594 # $other->merge_from($self);
601 # die 'Not implemented';
605 sub add_deleted_object
{
609 # ignore null and meta stream UUIDs
610 return if $uuid eq UUID_NULL
|| $uuid eq '0' x
16;
612 $self->deleted_objects->{$uuid} = {
614 deletion_time
=> scalar gmtime,
619 sub remove_deleted_object
{
622 delete $self->deleted_objects->{$uuid};
626 sub clear_deleted_objects
{
628 %{$self->deleted_objects} = ();
631 ##############################################################################
634 sub resolve_reference
{
636 my $wanted = shift // return;
637 my $search_in = shift;
640 if (!defined $text) {
641 $wanted =~ s/^\{REF:([^\}]+)\}$/$1/i;
642 ($wanted, $search_in, $text) = $wanted =~ /^([TUPANI])\@([TUPANIO]):(.*)$/i;
644 $wanted && $search_in && nonempty
($text) or return;
648 U
=> 'expand_username',
649 P
=> 'expand_password',
653 O
=> 'other_strings',
655 $wanted = $fields{$wanted} or return;
656 $search_in = $fields{$search_in} or return;
658 my $query = $search_in eq 'uuid' ? query
($search_in => uuid
($text))
659 : simple_expression_query
($text, '=~', $search_in);
661 my $entry = $self->entries->grep($query)->next;
664 return $entry->$wanted;
667 our %PLACEHOLDERS = (
668 # 'PLACEHOLDER' => sub { my ($entry, $arg) = @_; ... };
669 'TITLE' => sub { $_[0]->expand_title },
670 'USERNAME' => sub { $_[0]->expand_username },
671 'PASSWORD' => sub { $_[0]->expand_password },
672 'NOTES' => sub { $_[0]->expand_notes },
673 'S:' => sub { $_[0]->string_value($_[1]) },
674 'URL' => sub { $_[0]->expand_url },
675 'URL:RMVSCM' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
676 'URL:WITHOUTSCHEME' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
677 'URL:SCM' => sub { (split_url
($_[0]->url))[0] },
678 'URL:SCHEME' => sub { (split_url
($_[0]->url))[0] }, # non-standard
679 'URL:HOST' => sub { (split_url
($_[0]->url))[2] },
680 'URL:PORT' => sub { (split_url
($_[0]->url))[3] },
681 'URL:PATH' => sub { (split_url
($_[0]->url))[4] },
682 'URL:QUERY' => sub { (split_url
($_[0]->url))[5] },
683 'URL:HASH' => sub { (split_url
($_[0]->url))[6] }, # non-standard
684 'URL:FRAGMENT' => sub { (split_url
($_[0]->url))[6] }, # non-standard
685 'URL:USERINFO' => sub { (split_url
($_[0]->url))[1] },
686 'URL:USERNAME' => sub { (split_url
($_[0]->url))[7] },
687 'URL:PASSWORD' => sub { (split_url
($_[0]->url))[8] },
688 'UUID' => sub { local $_ = format_uuid
($_[0]->uuid); s/-//g; $_ },
689 'REF:' => sub { $_[0]->kdbx->resolve_reference($_[1]) },
690 'INTERNETEXPLORER' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('iexplore') },
691 'FIREFOX' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('firefox') },
692 'GOOGLECHROME' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('google-chrome') },
693 'OPERA' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('opera') },
694 'SAFARI' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('safari') },
695 'APPDIR' => sub { load_optional
('FindBin'); $FindBin::Bin
},
696 'GROUP' => sub { my $p = $_[0]->group; $p ? $p->name : undef },
697 'GROUP_PATH' => sub { $_[0]->path },
698 'GROUP_NOTES' => sub { my $p = $_[0]->group; $p ? $p->notes : undef },
707 'ENV:' => sub { $ENV{$_[1]} },
708 'ENV_DIRSEP' => sub { load_optional
('File::Spec')->catfile('', '') },
709 'ENV_PROGRAMFILES_X86' => sub { $ENV{'ProgramFiles(x86)'} || $ENV{'ProgramFiles'} },
712 'DT_SIMPLE' => sub { localtime-
>strftime('%Y%m%d%H%M%S') },
713 'DT_YEAR' => sub { localtime-
>strftime('%Y') },
714 'DT_MONTH' => sub { localtime-
>strftime('%m') },
715 'DT_DAY' => sub { localtime-
>strftime('%d') },
716 'DT_HOUR' => sub { localtime-
>strftime('%H') },
717 'DT_MINUTE' => sub { localtime-
>strftime('%M') },
718 'DT_SECOND' => sub { localtime-
>strftime('%S') },
719 'DT_UTC_SIMPLE' => sub { gmtime-
>strftime('%Y%m%d%H%M%S') },
720 'DT_UTC_YEAR' => sub { gmtime-
>strftime('%Y') },
721 'DT_UTC_MONTH' => sub { gmtime-
>strftime('%m') },
722 'DT_UTC_DAY' => sub { gmtime-
>strftime('%d') },
723 'DT_UTC_HOUR' => sub { gmtime-
>strftime('%H') },
724 'DT_UTC_MINUTE' => sub { gmtime-
>strftime('%M') },
725 'DT_UTC_SECOND' => sub { gmtime-
>strftime('%S') },
732 'HMACOTP' => sub { $_[0]->hmac_otp },
733 'TIMEOTP' => sub { $_[0]->time_otp },
734 'C:' => sub { '' }, # comment
742 ##############################################################################
747 $SAFE{$self} = shift if @_;
751 sub _remove_safe
{ delete $SAFE{$_[0]} }
756 $self->_safe and return $self;
760 $self->entries(history
=> 1)->each(sub {
761 push @strings, grep { $_->{protect
} } values %{$_->strings}, values %{$_->binaries};
764 $self->_safe(File
::KDBX
::Safe-
>new(\
@strings));
772 my $safe = $self->_safe or return $self;
782 throw
'Programmer error: Cannot call unlock_scoped in void context' if !defined wantarray;
784 return if !$self->is_locked;
785 require Scope
::Guard
;
786 my $guard = Scope
::Guard-
>new(sub { $self->lock });
795 my $safe = $self->_safe or return;
796 return $safe->peek($string);
800 sub is_locked
{ !!$_[0]->_safe }
802 ##############################################################################
805 # - Fixer tool. Can repair inconsistencies, including:
806 # - Orphaned binaries... not really a thing anymore since we now distribute binaries amongst entries
807 # - Unused custom icons (OFF, data loss)
809 # - All data types are valid
810 # - date times are correct
812 # - All UUIDs refer to things that exist
813 # - previous parent group
815 # - last selected group
816 # - last visible group
817 # - Enforce history size limits (ON)
818 # - Check headers/meta (ON)
819 # - Duplicate deleted objects (ON)
820 # - Duplicate window associations (OFF)
821 # - Header UUIDs match known ciphers/KDFs?
825 sub remove_empty_groups
{
828 $self->groups(algorithm
=> 'dfs')
829 ->where(-true
=> 'is_empty')
830 ->each(sub { push @removed, $_->remove });
835 sub remove_unused_icons
{
837 my %icons = map { $_->{uuid
} => 0 } @{$self->custom_icons};
839 $self->objects->each(sub { ++$icons{$_->custom_icon_uuid // ''} });
842 push @removed, $self->remove_custom_icon($_) for grep { $icons{$_} == 0 } keys %icons;
847 sub remove_duplicate_icons
{
852 for my $icon (@{$self->custom_icons}) {
853 my $digest = digest_data
('SHA256', $icon->{data
});
854 if (my $other = $seen{$digest}) {
855 $dup{$icon->{uuid
}} = $other->{uuid
};
858 $seen{$digest} = $icon;
863 while (my ($old_uuid, $new_uuid) = each %dup) {
865 ->where(custom_icon_uuid
=> $old_uuid)
866 ->each(sub { $_->custom_icon_uuid($new_uuid) });
867 push @removed, $self->remove_custom_icon($old_uuid);
877 my $max_items = $args{max_items
} // $self->history_max_items // HISTORY_DEFAULT_MAX_ITEMS
;
878 my $max_size = $args{max_size
} // $self->history_max_size // HISTORY_DEFAULT_MAX_SIZE
;
879 my $max_age = $args{max_age
} // $self->maintenance_history_days // HISTORY_DEFAULT_MAX_AGE
;
882 $self->entries->each(sub {
883 push @removed, $_->prune_history(
884 max_items
=> $max_items,
885 max_size
=> $max_size,
893 sub randomize_seeds
{
895 $self->encryption_iv(random_bytes
(16));
896 $self->inner_random_stream_key(random_bytes
(64));
897 $self->master_seed(random_bytes
(32));
898 $self->stream_start_bytes(random_bytes
(32));
899 $self->transform_seed(random_bytes
(32));
902 ##############################################################################
907 $KEYS{$self} = File
::KDBX
::Key-
>new(@_) if @_;
914 require File
::KDBX
::Key
::Composite
;
915 return File
::KDBX
::Key
::Composite-
>new(@_);
921 my %args = @_ % 2 == 1 ? (params
=> shift, @_) : @_;
923 my $params = $args{params
};
924 my $compat = $args{compatible
} // 1;
926 $params //= $self->kdf_parameters;
927 $params = {%{$params || {}}};
929 if (empty
$params || !defined $params->{+KDF_PARAM_UUID
}) {
930 $params->{+KDF_PARAM_UUID
} = KDF_UUID_AES
;
932 if ($params->{+KDF_PARAM_UUID
} eq KDF_UUID_AES
) {
933 # AES_CHALLENGE_RESPONSE is equivalent to AES if there are no challenge-response keys, and since
934 # non-KeePassXC implementations don't support challenge-response keys anyway, there's no problem with
935 # always using AES_CHALLENGE_RESPONSE for all KDBX4+ databases.
936 # For compatibility, we should not *write* AES_CHALLENGE_RESPONSE, but the dumper handles that.
937 if ($self->version >= KDBX_VERSION_4_0
) {
938 $params->{+KDF_PARAM_UUID
} = KDF_UUID_AES_CHALLENGE_RESPONSE
;
940 $params->{+KDF_PARAM_AES_SEED
} //= $self->transform_seed;
941 $params->{+KDF_PARAM_AES_ROUNDS
} //= $self->transform_rounds;
944 require File
::KDBX
::KDF
;
945 return File
::KDBX
::KDF-
>new(%$params);
950 $self->headers->{+HEADER_TRANSFORM_SEED
} =
951 $self->headers->{+HEADER_KDF_PARAMETERS
}{+KDF_PARAM_AES_SEED
} = shift if @_;
952 $self->headers->{+HEADER_TRANSFORM_SEED
} =
953 $self->headers->{+HEADER_KDF_PARAMETERS
}{+KDF_PARAM_AES_SEED
} //= random_bytes
(32);
956 sub transform_rounds
{
958 $self->headers->{+HEADER_TRANSFORM_ROUNDS
} =
959 $self->headers->{+HEADER_KDF_PARAMETERS
}{+KDF_PARAM_AES_ROUNDS
} = shift if @_;
960 $self->headers->{+HEADER_TRANSFORM_ROUNDS
} =
961 $self->headers->{+HEADER_KDF_PARAMETERS
}{+KDF_PARAM_AES_ROUNDS
} //= 100_000;
969 $args{uuid
} //= $self->headers->{+HEADER_CIPHER_ID
};
970 $args{iv
} //= $self->headers->{+HEADER_ENCRYPTION_IV
};
972 require File
::KDBX
::Cipher
;
973 return File
::KDBX
::Cipher-
>new(%args);
981 $args{stream_id
} //= delete $args{id
} // $self->inner_random_stream_id;
982 $args{key
} //= $self->inner_random_stream_key;
984 require File
::KDBX
::Cipher
;
985 File
::KDBX
::Cipher-
>new(%args);
988 sub inner_random_stream_id
{
990 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID
}
991 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID
} = shift if @_;
992 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID
}
993 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID
} //= do {
994 my $version = $self->minimum_version;
995 $version < KDBX_VERSION_4_0
? STREAM_ID_SALSA20
: STREAM_ID_CHACHA20
;
999 sub inner_random_stream_key
{
1002 # These are probably the same SvPV so erasing one will CoW, but erasing the second should do the
1004 erase \
$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY
};
1005 erase \
$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY
};
1006 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY
}
1007 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY
} = shift;
1009 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY
}
1010 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY
} //= random_bytes
(64); # 32
1013 #########################################################################################
1015 sub _handle_signal
{
1021 'entry.added' => \
&_handle_object_added
,
1022 'group.added' => \
&_handle_object_added
,
1023 'entry.removed' => \
&_handle_object_removed
,
1024 'group.removed' => \
&_handle_object_removed
,
1025 'entry.uuid.changed' => \
&_handle_entry_uuid_changed
,
1026 'group.uuid.changed' => \
&_handle_group_uuid_changed
,
1028 my $handler = $handlers{$type} or return;
1029 $self->$handler($object, @_);
1032 sub _handle_object_added
{
1035 $self->remove_deleted_object($object->uuid);
1038 sub _handle_object_removed
{
1041 my $old_uuid = $object->{uuid
} // return;
1043 my $meta = $self->meta;
1044 $self->recycle_bin_uuid(UUID_NULL
) if $old_uuid eq ($meta->{recycle_bin_uuid
} // '');
1045 $self->entry_templates_group(UUID_NULL
) if $old_uuid eq ($meta->{entry_templates_group
} // '');
1046 $self->last_selected_group(UUID_NULL
) if $old_uuid eq ($meta->{last_selected_group
} // '');
1047 $self->last_top_visible_group(UUID_NULL
) if $old_uuid eq ($meta->{last_top_visible_group
} // '');
1049 $self->add_deleted_object($old_uuid);
1052 sub _handle_entry_uuid_changed
{
1055 my $new_uuid = shift;
1056 my $old_uuid = shift // return;
1058 my $old_pretty = format_uuid
($old_uuid);
1059 my $new_pretty = format_uuid
($new_uuid);
1060 my $fieldref_match = qr/\{REF:([TUPANI])\@I:\Q$old_pretty\E\}/is;
1062 $self->entries->each(sub {
1063 $_->previous_parent_group($new_uuid) if $old_uuid eq ($_->{previous_parent_group
} // '');
1065 for my $string (values %{$_->strings}) {
1066 next if !defined $string->{value
} || $string->{value
} !~ $fieldref_match;
1067 my $txn = $_->begin_work;
1068 $string->{value
} =~ s/$fieldref_match/{REF:$1\@I:$new_pretty}/g;
1074 sub _handle_group_uuid_changed
{
1077 my $new_uuid = shift;
1078 my $old_uuid = shift // return;
1080 my $meta = $self->meta;
1081 $self->recycle_bin_uuid($new_uuid) if $old_uuid eq ($meta->{recycle_bin_uuid
} // '');
1082 $self->entry_templates_group($new_uuid) if $old_uuid eq ($meta->{entry_templates_group
} // '');
1083 $self->last_selected_group($new_uuid) if $old_uuid eq ($meta->{last_selected_group
} // '');
1084 $self->last_top_visible_group($new_uuid) if $old_uuid eq ($meta->{last_top_visible_group
} // '');
1086 $self->groups->each(sub {
1087 $_->last_top_visible_entry($new_uuid) if $old_uuid eq ($_->{last_top_visible_entry
} // '');
1088 $_->previous_parent_group($new_uuid) if $old_uuid eq ($_->{previous_parent_group
} // '');
1090 $self->entries->each(sub {
1091 $_->previous_parent_group($new_uuid) if $old_uuid eq ($_->{previous_parent_group
} // '');
1095 #########################################################################################
1098 #########################################################################################
1100 sub TO_JSON
{ +{%{$_[0]}} }
1110 =for markdown [![Linux](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml/badge.svg)](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml)
1111 [![macOS](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml/badge.svg)](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml)
1112 [![Windows](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml/badge.svg)](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml)
1114 =for HTML <a title="Linux" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml/badge.svg"></a>
1115 <a title="macOS" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml/badge.svg"></a>
1116 <a title="Windows" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml/badge.svg"></a>
1120 File::KDBX - Encrypted database to store secret text and files
1130 # Create a new database from scratch
1131 my $kdbx = File::KDBX->new;
1133 # Add some objects to the database
1134 my $group = $kdbx->add_group(
1135 name => 'Passwords',
1137 my $entry = $group->add_entry(
1139 username => 'mreynolds',
1140 password => 's3cr3t',
1143 # Save the database to the filesystem
1144 $kdbx->dump_file('passwords.kdbx', 'masterpw changeme');
1146 # Load the database from the filesystem into a new database instance
1147 my $kdbx2 = File::KDBX->load_file('passwords.kdbx', 'masterpw changeme');
1149 # Iterate over database entries, print entry titles
1150 $kdbx2->entries->each(sub($entry, @) {
1151 say 'Entry: ', $entry->title;
1154 See L</RECIPES> for more examples.
1158 B<File::KDBX> provides everything you need to work with KDBX databases. A KDBX database is a hierarchical
1159 object database which is commonly used to store secret information securely. It was developed for the KeePass
1160 password safe. See L</"Introduction to KDBX"> for more information about KDBX.
1162 This module lets you query entries, create new entries, delete entries, modify entries and more. The
1163 distribution also includes various parsers and generators for serializing and persisting databases.
1165 The design of this software was influenced by the L<KeePassXC|https://github.com/keepassxreboot/keepassxc>
1166 implementation of KeePass as well as the L<File::KeePass> module. B<File::KeePass> is an alternative module
1167 that works well in most cases but has a small backlog of bugs and security issues and also does not work with
1168 newer KDBX version 4 files. If you're coming here from the B<File::KeePass> world, you might be interested in
1169 L<File::KeePass::KDBX> that is a drop-in replacement for B<File::KeePass> that uses B<File::KDBX> for storage.
1171 This software is a B<pre-1.0 release>. The interface should be considered pretty stable, but there might be
1172 minor changes up until a 1.0 release. Breaking changes will be noted in the F<Changes> file.
1180 ☑ Read and write KDBX version 3 - version 4.1
1184 ☑ Read and write KDB files (requires L<File::KeePass>)
1188 ☑ Unicode character strings
1192 ☑ L</"Simple Expression"> Searching
1196 ☑ L<Placeholders|File::KDBX::Entry/Placeholders> and L<field references|/resolve_reference>
1200 ☑ L<One-time passwords|File::KDBX::Entry/"One-time Passwords">
1204 ☑ L<Very secure|/SECURITY>
1208 ☑ L</"Memory Protection">
1212 ☑ Challenge-response key components, like L<YubiKey|File::KDBX::Key::YubiKey>
1216 ☑ Variety of L<key file|File::KDBX::Key::File> types: binary, hexed, hashed, XML v1 and v2
1220 ☑ Pluggable registration of different kinds of ciphers and key derivation functions
1224 ☑ Built-in database maintenance functions
1228 ☑ Pretty fast, with L<XS optimizations|File::KDBX::XS> available
1232 ☒ Database synchronization / merging (not yet)
1236 =head2 Introduction to KDBX
1238 A KDBX database consists of a tree of I<groups> and I<entries>, with a single I<root> group. Entries can
1239 contain zero or more key-value pairs of I<strings> and zero or more I<binaries> (i.e. octet strings). Groups,
1240 entries, strings and binaries: that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is
1241 associated with each entry, group and the database as a whole.
1243 You can think of a KDBX database kind of like a file system, where groups are directories, entries are files,
1244 and strings and binaries make up a file's contents.
1246 Databases are typically persisted as encrypted, compressed files. They are usually accessed directly (i.e.
1247 not over a network). The primary focus of this type of database is data security. It is ideal for storing
1248 relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as
1249 have the correct I<master key>. Even if the database file were to be "leaked" to the public Internet, it
1250 should be virtually impossible to crack with a strong key. The KDBX format is most often used by password
1251 managers to store passwords so that users can know a single strong password and not have to reuse passwords
1252 across different websites. See L</SECURITY> for an overview of security considerations.
1264 =head2 inner_headers
1270 =head2 deleted_objects
1272 Hash of UUIDs for objects that have been deleted. This includes groups, entries and even custom icons.
1276 Bytes contained within the encrypted layer of a KDBX file. This is only set when using
1277 L<File::KDBX::Loader::Raw>.
1281 A text string associated with the database. Often unset.
1285 The UUID of a cipher used to encrypt the database when stored as a file.
1287 See L<File::KDBX::Cipher>.
1289 =head2 compression_flags
1291 Configuration for whether or not and how the database gets compressed. See
1292 L<File::KDBX::Constants/":compression">.
1296 The master seed is a string of 32 random bytes that is used as salt in hashing the master key when loading
1297 and saving the database. If a challenge-response key is used in the master key, the master seed is also the
1300 The master seed I<should> be changed each time the database is saved to file.
1302 =head2 transform_seed
1304 The transform seed is a string of 32 random bytes that is used in the key derivation function, either as the
1305 salt or the key (depending on the algorithm).
1307 The transform seed I<should> be changed each time the database is saved to file.
1309 =head2 transform_rounds
1311 The number of rounds or iterations used in the key derivation function. Increasing this number makes loading
1312 and saving the database slower by design in order to make dictionary and brute force attacks more costly.
1314 =head2 encryption_iv
1316 The initialization vector used by the cipher.
1318 The encryption IV I<should> be changed each time the database is saved to file.
1320 =head2 inner_random_stream_key
1322 The encryption key (possibly including the IV, depending on the cipher) used to encrypt the protected strings
1323 within the database.
1325 =head2 stream_start_bytes
1327 A string of 32 random bytes written in the header and encrypted in the body. If the bytes do not match when
1328 loading a file then the wrong master key was used or the file is corrupt. Only KDBX 2 and KDBX 3 files use
1329 this. KDBX 4 files use an improved HMAC method to verify the master key and data integrity of the header and
1332 =head2 inner_random_stream_id
1334 A number indicating the cipher algorithm used to encrypt the protected strings within the database, usually
1335 Salsa20 or ChaCha20. See L<File::KDBX::Constants/":random_stream">.
1337 =head2 kdf_parameters
1339 A hash/dict of key-value pairs used to configure the key derivation function. This is the KDBX4+ way to
1340 configure the KDF, superceding L</transform_seed> and L</transform_rounds>.
1344 The name of the software used to generate the KDBX file.
1348 The header hash used to verify that the file header is not corrupt. (KDBX 2 - KDBX 3.1, removed KDBX 4.0)
1350 =head2 database_name
1352 Name of the database.
1354 =head2 database_name_changed
1356 Timestamp indicating when the database name was last changed.
1358 =head2 database_description
1360 Description of the database
1362 =head2 database_description_changed
1364 Timestamp indicating when the database description was last changed.
1366 =head2 default_username
1368 When a new entry is created, the I<UserName> string will be populated with this value.
1370 =head2 default_username_changed
1372 Timestamp indicating when the default username was last changed.
1376 A color associated with the database (in the form C<#ffffff> where "f" is a hexidecimal digit). Some agents
1377 use this to help users visually distinguish between different databases.
1379 =head2 master_key_changed
1381 Timestamp indicating when the master key was last changed.
1383 =head2 master_key_change_rec
1385 Number of days until the agent should prompt to recommend changing the master key.
1387 =head2 master_key_change_force
1389 Number of days until the agent should prompt to force changing the master key.
1391 Note: This is purely advisory. It is up to the individual agent software to actually enforce it.
1392 B<File::KDBX> does NOT enforce it.
1396 Array of custom icons that can be associated with groups and entries.
1398 This list can be managed with the methods L</add_custom_icon> and L</remove_custom_icon>.
1400 =head2 recycle_bin_enabled
1402 Boolean indicating whether removed groups and entries should go to a recycle bin or be immediately deleted.
1404 =head2 recycle_bin_uuid
1406 The UUID of a group used to store thrown-away groups and entries.
1408 =head2 recycle_bin_changed
1410 Timestamp indicating when the recycle bin group was last changed.
1412 =head2 entry_templates_group
1414 The UUID of a group containing template entries used when creating new entries.
1416 =head2 entry_templates_group_changed
1418 Timestamp indicating when the entry templates group was last changed.
1420 =head2 last_selected_group
1422 The UUID of the previously-selected group.
1424 =head2 last_top_visible_group
1426 The UUID of the group visible at the top of the list.
1428 =head2 history_max_items
1430 The maximum number of historical entries that should be kept for each entry. Default is 10.
1432 =head2 history_max_size
1434 The maximum total size (in bytes) that each individual entry's history is allowed to grow. Default is 6 MiB.
1436 =head2 maintenance_history_days
1438 The maximum age (in days) historical entries should be kept. Default it 365.
1440 =head2 settings_changed
1442 Timestamp indicating when the database settings were last updated.
1444 =head2 protect_title
1446 Alias of the L</memory_protection> setting for the I<Title> string.
1448 =head2 protect_username
1450 Alias of the L</memory_protection> setting for the I<UserName> string.
1452 =head2 protect_password
1454 Alias of the L</memory_protection> setting for the I<Password> string.
1458 Alias of the L</memory_protection> setting for the I<URL> string.
1460 =head2 protect_notes
1462 Alias of the L</memory_protection> setting for the I<Notes> string.
1468 $kdbx = File::KDBX->new(%attributes);
1469 $kdbx = File::KDBX->new($kdbx); # copy constructor
1471 Construct a new L<File::KDBX>.
1475 $kdbx = $kdbx->init(%attributes);
1477 Initialize a L<File::KDBX> with a set of attributes. Returns itself to allow method chaining.
1479 This is called by L</new>.
1483 $kdbx = $kdbx->reset;
1485 Set a L<File::KDBX> to an empty state, ready to load a KDBX file or build a new one. Returns itself to allow
1490 $kdbx_copy = $kdbx->clone;
1491 $kdbx_copy = File::KDBX->new($kdbx);
1493 Clone a L<File::KDBX>. The clone will be an exact copy and completely independent of the original.
1503 $kdbx = KDBX::File->load(\$string, $key);
1504 $kdbx = KDBX::File->load(*IO, $key);
1505 $kdbx = KDBX::File->load($filepath, $key);
1506 $kdbx->load(...); # also instance method
1508 $kdbx = File::KDBX->load_string($string, $key);
1509 $kdbx = File::KDBX->load_string(\$string, $key);
1510 $kdbx->load_string(...); # also instance method
1512 $kdbx = File::KDBX->load_file($filepath, $key);
1513 $kdbx->load_file(...); # also instance method
1515 $kdbx = File::KDBX->load_handle($fh, $key);
1516 $kdbx = File::KDBX->load_handle(*IO, $key);
1517 $kdbx->load_handle(...); # also instance method
1519 Load a KDBX file from a string buffer, IO handle or file from a filesystem.
1521 L<File::KDBX::Loader> does the heavy lifting.
1531 $kdbx->dump(\$string, $key);
1532 $kdbx->dump(*IO, $key);
1533 $kdbx->dump($filepath, $key);
1535 $kdbx->dump_string(\$string, $key);
1536 \$string = $kdbx->dump_string($key);
1538 $kdbx->dump_file($filepath, $key);
1540 $kdbx->dump_handle($fh, $key);
1541 $kdbx->dump_handle(*IO, $key);
1543 Dump a KDBX file to a string buffer, IO handle or file in a filesystem.
1545 L<File::KDBX::Dumper> does the heavy lifting.
1547 =head2 user_agent_string
1549 $string = $kdbx->user_agent_string;
1551 Get a text string identifying the database client software.
1553 =head2 memory_protection
1555 \%settings = $kdbx->memory_protection
1556 $kdbx->memory_protection(\%settings);
1558 $bool = $kdbx->memory_protection($string_key);
1559 $kdbx->memory_protection($string_key => $bool);
1561 Get or set memory protection settings. This globally (for the whole database) configures whether and which of
1562 the standard strings should be memory-protected. The default setting is to memory-protect only I<Password>
1565 Memory protection can be toggled individually for each entry string, and individual settings take precedence
1566 over these global settings.
1568 =head2 minimum_version
1570 $version = $kdbx->minimum_version;
1572 Determine the minimum file version required to save a database losslessly. Using certain databases features
1573 might increase this value. For example, setting the KDF to Argon2 will increase the minimum version to at
1574 least C<KDBX_VERSION_4_0> (i.e. C<0x00040000>) because Argon2 was introduced with KDBX4.
1576 This method never returns less than C<KDBX_VERSION_3_1> (i.e. C<0x00030001>). That file version is so
1577 ubiquitous and well-supported, there are seldom reasons to dump in a lesser format nowadays.
1579 B<WARNING:> If you dump a database with a minimum version higher than the current L</version>, the dumper will
1580 typically issue a warning and automatically upgrade the database. This seems like the safest behavior in order
1581 to avoid data loss, but lower versions have the benefit of being compatible with more software. It is possible
1582 to prevent auto-upgrades by explicitly telling the dumper which version to use, but you do run the risk of
1583 data loss. A database will never be automatically downgraded.
1587 $group = $kdbx->root;
1588 $kdbx->root($group);
1590 Get or set a database's root group. You don't necessarily need to explicitly create or set a root group
1591 because it autovivifies when adding entries and groups to the database.
1593 Every database has only a single root group at a time. Some old KDB files might have multiple root groups.
1594 When reading such files, a single implicit root group is created to contain the actual root groups. When
1595 writing to such a format, if the root group looks like it was implicitly created then it won't be written and
1596 the resulting file might have multiple root groups, as it was before loading. This allows working with older
1597 files without changing their written internal structure while still adhering to modern semantics while the
1600 The root group of a KDBX database contains all of the database's entries and other groups. If you replace the
1601 root group, you are essentially replacing the entire database contents with something else.
1603 =head2 trace_lineage
1605 \@lineage = $kdbx->trace_lineage($group);
1606 \@lineage = $kdbx->trace_lineage($group, $base_group);
1607 \@lineage = $kdbx->trace_lineage($entry);
1608 \@lineage = $kdbx->trace_lineage($entry, $base_group);
1610 Get the direct line of ancestors from C<$base_group> (default: the root group) to a group or entry. The
1611 lineage includes the base group but I<not> the target group or entry. Returns C<undef> if the target is not in
1612 the database structure.
1616 $group = $kdbx->recycle_bin;
1617 $kdbx->recycle_bin($group);
1619 Get or set the recycle bin group. Returns C<undef> if there is no recycle bin and L</recycle_bin_enabled> is
1620 false, otherwise the current recycle bin or an autovivified recycle bin group is returned.
1622 =head2 entry_templates
1624 $group = $kdbx->entry_templates;
1625 $kdbx->entry_templates($group);
1627 Get or set the entry templates group. May return C<undef> if unset.
1629 =head2 last_selected
1631 $group = $kdbx->last_selected;
1632 $kdbx->last_selected($group);
1634 Get or set the last selected group. May return C<undef> if unset.
1636 =head2 last_top_visible
1638 $group = $kdbx->last_top_visible;
1639 $kdbx->last_top_visible($group);
1641 Get or set the last top visible group. May return C<undef> if unset.
1645 $kdbx->add_group($group);
1646 $kdbx->add_group(%group_attributes, %options);
1648 Add a group to a database. This is equivalent to identifying a parent group and calling
1649 L<File::KDBX::Group/add_group> on the parent group, forwarding the arguments. Available options:
1655 C<group> - Group object or group UUID to add the group to (default: root group)
1661 \&iterator = $kdbx->groups(%options);
1662 \&iterator = $kdbx->groups($base_group, %options);
1664 Get an L<File::KDBX::Iterator> over I<groups> within a database. Options:
1670 C<base> - Only include groups within a base group (same as C<$base_group>) (default: L</root>)
1674 C<inclusive> - Include the base group in the results (default: true)
1678 C<algorithm> - Search algorithm, one of C<ids>, C<bfs> or C<dfs> (default: C<ids>)
1684 $kdbx->add_entry($entry, %options);
1685 $kdbx->add_entry(%entry_attributes, %options);
1687 Add a entry to a database. This is equivalent to identifying a parent group and calling
1688 L<File::KDBX::Group/add_entry> on the parent group, forwarding the arguments. Available options:
1694 C<group> - Group object or group UUID to add the entry to (default: root group)
1700 \&iterator = $kdbx->entries(%options);
1701 \&iterator = $kdbx->entries($base_group, %options);
1703 Get an L<File::KDBX::Iterator> over I<entries> within a database. Supports the same options as L</groups>,
1710 C<auto_type> - Only include entries with auto-type enabled (default: false, include all)
1714 C<searching> - Only include entries within groups with searching enabled (default: false, include all)
1718 C<history> - Also include historical entries (default: false, include only current entries)
1724 \&iterator = $kdbx->objects(%options);
1725 \&iterator = $kdbx->objects($base_group, %options);
1727 Get an L<File::KDBX::Iterator> over I<objects> within a database. Groups and entries are considered objects,
1728 so this is essentially a combination of L</groups> and L</entries>. This won't often be useful, but it can be
1729 convenient for maintenance tasks. This method takes the same options as L</groups> and L</entries>.
1733 \%icon = $kdbx->custom_icon($uuid);
1734 $kdbx->custom_icon($uuid => \%icon);
1735 $kdbx->custom_icon(%icon);
1736 $kdbx->custom_icon(uuid => $value, %icon);
1738 Get or set custom icons.
1740 =head2 custom_icon_data
1742 $image_data = $kdbx->custom_icon_data($uuid);
1744 Get a custom icon image data.
1746 =head2 add_custom_icon
1748 $uuid = $kdbx->add_custom_icon($image_data, %attributes);
1749 $uuid = $kdbx->add_custom_icon(%attributes);
1751 Add a custom icon and get its UUID. If not provided, a random UUID will be generated. Possible attributes:
1757 C<uuid> - Icon UUID (default: autogenerated)
1761 C<data> - Image data (same as C<$image_data>)
1765 C<name> - Name of the icon (text, KDBX4.1+)
1769 C<last_modification_time> - Just what it says (datetime, KDBX4.1+)
1773 =head2 remove_custom_icon
1775 $kdbx->remove_custom_icon($uuid);
1777 Remove a custom icon.
1781 \%all_data = $kdbx->custom_data;
1782 $kdbx->custom_data(\%all_data);
1784 \%data = $kdbx->custom_data($key);
1785 $kdbx->custom_data($key => \%data);
1786 $kdbx->custom_data(%data);
1787 $kdbx->custom_data(key => $value, %data);
1789 Get and set custom data. Custom data is metadata associated with a database.
1791 Each data item can have a few attributes associated with it.
1797 C<key> - A unique text string identifier used to look up the data item (required)
1801 C<value> - A text string value (required)
1805 C<last_modification_time> (optional, KDBX4.1+)
1809 =head2 custom_data_value
1811 $value = $kdbx->custom_data_value($key);
1813 Exactly the same as L</custom_data> except returns just the custom data's value rather than a structure of
1814 attributes. This is a shortcut for:
1816 my $data = $kdbx->custom_data($key);
1817 my $value = defined $data ? $data->{value} : undef;
1819 =head2 public_custom_data
1821 \%all_data = $kdbx->public_custom_data;
1822 $kdbx->public_custom_data(\%all_data);
1824 $value = $kdbx->public_custom_data($key);
1825 $kdbx->public_custom_data($key => $value);
1827 Get and set public custom data. Public custom data is similar to custom data but different in some important
1828 ways. Public custom data:
1834 can store strings, booleans and up to 64-bit integer values (custom data can only store text values)
1838 is NOT encrypted within a KDBX file (hence the "public" part of the name)
1842 is a plain hash/dict of key-value pairs with no other associated fields (like modification times)
1846 =head2 add_deleted_object
1848 $kdbx->add_deleted_object($uuid);
1850 Add a UUID to the deleted objects list. This list is used to support automatic database merging.
1852 You typically do not need to call this yourself because the list will be populated automatically as objects
1855 =head2 remove_deleted_object
1857 $kdbx->remove_deleted_object($uuid);
1859 Remove a UUID from the deleted objects list. This list is used to support automatic database merging.
1861 You typically do not need to call this yourself because the list will be maintained automatically as objects
1864 =head2 clear_deleted_objects
1866 Remove all UUIDs from the deleted objects list. This list is used to support automatic database merging, but
1867 if you don't need merging then you can clear deleted objects to reduce the database file size.
1869 =head2 resolve_reference
1871 $string = $kdbx->resolve_reference($reference);
1872 $string = $kdbx->resolve_reference($wanted, $search_in, $expression);
1874 Resolve a L<field reference|https://keepass.info/help/base/fieldrefs.html>. A field reference is a kind of
1875 string placeholder. You can use a field reference to refer directly to a standard field within an entry. Field
1876 references are resolved automatically while expanding entry strings (i.e. replacing placeholders), but you can
1877 use this method to resolve on-the-fly references that aren't part of any actual string in the database.
1879 If the reference does not resolve to any field, C<undef> is returned. If the reference resolves to multiple
1880 fields, only the first one is returned (in the same order as iterated by L</entries>). To avoid ambiguity, you
1881 can refer to a specific entry by its UUID.
1883 The syntax of a reference is: C<< {REF:<WantedField>@<SearchIn>:<Text>} >>. C<Text> is a
1884 L</"Simple Expression">. C<WantedField> and C<SearchIn> are both single character codes representing a field:
1914 C<O> - Other custom strings
1918 Since C<O> does not represent any specific field, it cannot be used as the C<WantedField>.
1922 To get the value of the I<UserName> string of the first entry with "My Bank" in the title:
1924 my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
1925 # OR the {REF:...} wrapper is optional
1926 my $username = $kdbx->resolve_reference('U@T:"My Bank"');
1927 # OR separate the arguments
1928 my $username = $kdbx->resolve_reference(U => T => '"My Bank"');
1930 Note how the text is a L</"Simple Expression">, so search terms with spaces must be surrounded in double
1933 To get the I<Password> string of a specific entry (identified by its UUID):
1935 my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');
1941 Encrypt all protected strings and binaries in a database. The encrypted data is stored in
1942 a L<File::KDBX::Safe> associated with the database and the actual values will be replaced with C<undef> to
1943 indicate their protected state. Returns itself to allow method chaining.
1945 You can call C<lock> on an already-locked database to memory-protect any unprotected strings and binaries
1946 added after the last time the database was locked.
1952 Decrypt all protected strings and binaries in a database, replacing C<undef> value placeholders with their
1953 actual, unprotected values. Returns itself to allow method chaining.
1955 =head2 unlock_scoped
1957 $guard = $kdbx->unlock_scoped;
1959 Unlock a database temporarily, relocking when the guard is released (typically at the end of a scope). Returns
1960 C<undef> if the database is already unlocked.
1962 See L</lock> and L</unlock>.
1967 my $guard = $kdbx->unlock_scoped;
1970 # $kdbx is now memory-locked
1974 $string = $kdbx->peek(\%string);
1975 $string = $kdbx->peek(\%binary);
1977 Peek at the value of a protected string or binary without unlocking the whole database. The argument can be
1978 a string or binary hashref as returned by L<File::KDBX::Entry/string> or L<File::KDBX::Entry/binary>.
1982 $bool = $kdbx->is_locked;
1984 Get whether or not a database's contents are in a locked (i.e. memory-protected) state. If this is true, then
1985 some or all of the protected strings and binaries within the database will be unavailable (literally have
1986 C<undef> values) until L</unlock> is called.
1988 =head2 remove_empty_groups
1990 $kdbx->remove_empty_groups;
1992 Remove groups with no subgroups and no entries.
1994 =head2 remove_unused_icons
1996 $kdbx->remove_unused_icons;
1998 Remove icons that are not associated with any entry or group in the database.
2000 =head2 remove_duplicate_icons
2002 $kdbx->remove_duplicate_icons;
2004 Remove duplicate icons as determined by hashing the icon data.
2006 =head2 prune_history
2008 $kdbx->prune_history(%options);
2010 Remove just as many older historical entries as necessary to get under certain limits.
2016 C<max_items> - Maximum number of historical entries to keep (default: value of L</history_max_items>, no limit: -1)
2020 C<max_size> - Maximum total size (in bytes) of historical entries to keep (default: value of L</history_max_size>, no limit: -1)
2024 C<max_age> - Maximum age (in days) of historical entries to keep (default: 365, no limit: -1)
2028 =head2 randomize_seeds
2030 $kdbx->randomize_seeds;
2032 Set various keys, seeds and IVs to random values. These values are used by the cryptographic functions that
2033 secure the database when dumped. The attributes that will be randomized are:
2043 L</inner_random_stream_key>
2051 L</stream_start_bytes>
2059 Randomizing these values has no effect on a loaded database. These are only used when a database is dumped.
2060 You normally do not need to call this method explicitly because the dumper does it explicitly by default.
2065 $key = $kdbx->key($key);
2066 $key = $kdbx->key($primitive);
2068 Get or set a L<File::KDBX::Key>. This is the master key (e.g. a password or a key file that can decrypt
2069 a database). You can also pass a primitive castable to a B<Key>. See L<File::KDBX::Key/new> for an explanation
2070 of what the primitive can be.
2072 You generally don't need to call this directly because you can provide the key directly to the loader or
2073 dumper when loading or dumping a KDBX file.
2075 =head2 composite_key
2077 $key = $kdbx->composite_key($key);
2078 $key = $kdbx->composite_key($primitive);
2080 Construct a L<File::KDBX::Key::Composite> from a B<Key> or primitive. See L<File::KDBX::Key/new> for an
2081 explanation of what the primitive can be. If the primitive does not represent a composite key, it will be
2084 You generally don't need to call this directly. The loader and dumper use it to transform a master key into
2085 a raw encryption key.
2089 $kdf = $kdbx->kdf(%options);
2090 $kdf = $kdbx->kdf(\%parameters, %options);
2092 Get a L<File::KDBX::KDF> (key derivation function).
2100 C<params> - KDF parameters, same as C<\%parameters> (default: value of L</kdf_parameters>)
2106 $cipher = $kdbx->cipher(key => $key);
2107 $cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);
2109 Get a L<File::KDBX::Cipher> capable of encrypting and decrypting the body of a database file.
2111 A key is required. This should be a raw encryption key made up of a fixed number of octets (depending on the
2112 cipher), not a L<File::KDBX::Key> or primitive.
2114 If not passed, the UUID comes from C<< $kdbx->headers->{cipher_id} >> and the encryption IV comes from
2115 C<< $kdbx->headers->{encryption_iv} >>.
2117 You generally don't need to call this directly. The loader and dumper use it to decrypt and encrypt KDBX
2120 =head2 random_stream
2122 $cipher = $kdbx->random_stream;
2123 $cipher = $kdbx->random_stream(id => $stream_id, key => $key);
2125 Get a L<File::KDBX::Cipher::Stream> for decrypting and encrypting protected values.
2127 If not passed, the ID and encryption key comes from C<< $kdbx->headers->{inner_random_stream_id} >> and
2128 C<< $kdbx->headers->{inner_random_stream_key} >> (respectively) for KDBX3 files and from
2129 C<< $kdbx->inner_headers->{inner_random_stream_key} >> and
2130 C<< $kdbx->inner_headers->{inner_random_stream_id} >> (respectively) for KDBX4 files.
2132 You generally don't need to call this directly. The loader and dumper use it to scramble protected strings.
2134 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
2138 =head2 Create a new database
2140 my $kdbx = File::KDBX->new;
2142 my $group = $kdbx->add_group(name => 'Passwords);
2143 my $entry = $group->add_entry(
2144 title => 'WayneCorp',
2145 username => 'bwayne',
2146 password => 'iambatman',
2147 url => 'https://example.com/login'
2149 $entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');
2151 $kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');
2153 =head2 Read an existing database
2155 my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
2156 $kdbx->unlock; # cause $entry->password below to be defined
2158 $kdbx->entries->each(sub($entry, @) {
2159 say 'Found password for: ', $entry->title;
2160 say ' Username: ', $entry->username;
2161 say ' Password: ', $entry->password;
2164 =head2 Search for entries
2166 my @entries = $kdbx->entries(searching => 1)
2167 ->grep(title => 'WayneCorp')
2168 ->each; # return all matches
2170 The C<searching> option limits results to only entries within groups with searching enabled. Other options are
2171 also available. See L</entries>.
2173 See L</QUERY> for many more query examples.
2175 =head2 Search for entries by auto-type window association
2177 my $window_title = 'WayneCorp - Mozilla Firefox';
2179 my $entries = $kdbx->entries(auto_type => 1)
2181 my ($ata) = grep { $_->{window} =~ /\Q$window_title\E/i } @{$_->auto_type_associations};
2182 return [$_, $ata->{keystroke_sequence}] if $ata;
2185 my ($entry, $keys) = @$_;
2186 say 'Entry title: ', $entry->title, ', key sequence: ', $keys;
2191 Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}
2193 =head2 Remove entries from a database
2196 ->grep(notes => {'=~' => qr/too old/i})
2197 ->each(sub { $_->recycle });
2199 Recycle all entries with the string "too old" appearing in the B<Notes> string.
2201 =head2 Remove empty groups
2203 $kdbx->groups(algorithm => 'dfs')
2204 ->where(-true => 'is_empty')
2207 With the search/iteration C<algorithm> set to "dfs", groups will be ordered deepest first and the root group
2208 will be last. This allows removing groups that only contain empty groups.
2210 This can also be done with one call to L</remove_empty_groups>.
2214 One of the biggest threats to your database security is how easily the encryption key can be brute-forced.
2215 Strong brute-force protection depends on:
2221 Using unguessable passwords, passphrases and key files.
2225 Using a brute-force resistent key derivation function.
2229 The first factor is up to you. This module does not enforce strong master keys. It is up to you to pick or
2230 generate strong keys.
2232 The KDBX format allows for the key derivation function to be tuned. The idea is that you want each single
2233 brute-foce attempt to be expensive (in terms of time, CPU usage or memory usage), so that making a lot of
2234 attempts (which would be required if you have a strong master key) gets I<really> expensive.
2236 How expensive you want to make each attempt is up to you and can depend on the application.
2238 This and other KDBX-related security issues are covered here more in depth:
2239 L<https://keepass.info/help/base/security.html>
2241 Here are other security risks you should be thinking about:
2245 This distribution uses the excellent L<CryptX> and L<Crypt::Argon2> packages to handle all crypto-related
2246 functions. As such, a lot of the security depends on the quality of these dependencies. Fortunately these
2247 modules are maintained and appear to have good track records.
2249 The KDBX format has evolved over time to incorporate improved security practices and cryptographic functions.
2250 This package uses the following functions for authentication, hashing, encryption and random number
2293 At the time of this writing, I am not aware of any successful attacks against any of these functions. These
2294 are among the most-analyzed and widely-adopted crypto functions available.
2296 The KDBX format allows the body cipher and key derivation function to be configured. If a flaw is discovered
2297 in one of these functions, you can hopefully just switch to a better function without needing to update this
2298 software. A later software release may phase out the use of any functions which are no longer secure.
2300 =head2 Memory Protection
2302 It is not a good idea to keep secret information unencrypted in system memory for longer than is needed. The
2303 address space of your program can generally be read by a user with elevated privileges on the system. If your
2304 system is memory-constrained or goes into a hibernation mode, the contents of your address space could be
2305 written to a disk where it might be persisted for long time.
2307 There might be system-level things you can do to reduce your risk, like using swap encryption and limiting
2308 system access to your program's address space while your program is running.
2310 B<File::KDBX> helps minimize (but not eliminate) risk by keeping secrets encrypted in memory until accessed
2311 and zeroing out memory that holds secrets after they're no longer needed, but it's not a silver bullet.
2313 For one thing, the encryption key is stored in the same address space. If core is dumped, the encryption key
2314 is available to be found out. But at least there is the chance that the encryption key and the encrypted
2315 secrets won't both be paged out together while memory-constrained.
2317 Another problem is that some perls (somewhat notoriously) copy around memory behind the scenes willy nilly,
2318 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
2319 be impossible. The good news is that perls with SvPV copy-on-write (enabled by default beginning with perl
2320 5.20) are much better in this regard. With COW, it's mostly possible to know what operations will cause perl
2321 to copy the memory of a scalar string, and the number of copies will be significantly reduced. There is a unit
2322 test named F<t/memory-protection.t> in this distribution that can be run on POSIX systems to determine how
2323 well B<File::KDBX> memory protection is working.
2325 Memory protection also depends on how your application handles secrets. If your app code is handling scalar
2326 strings with secret information, it's up to you to make sure its memory is zeroed out when no longer needed.
2327 L<File::KDBX::Util/erase> et al. provide some tools to help accomplish this. Or if you're not too concerned
2328 about the risks memory protection is meant to mitigate, then maybe don't worry about it. The security policy
2329 of B<File::KDBX> is to try hard to keep secrets protected while in memory so that your app might claim a high
2330 level of security, in case you care about that.
2332 There are some memory protection strategies that B<File::KDBX> does NOT use today but could in the future:
2334 Many systems allow programs to mark unswappable pages. Secret information should ideally be stored in such
2335 pages. You could potentially use L<mlockall(2)> (or equivalent for your system) in your own application to
2336 prevent the entire address space from being swapped.
2338 Some systems provide special syscalls for storing secrets in memory while keeping the encryption key outside
2339 of the program's address space, like C<CryptProtectMemory> for Windows. This could be a good option, though
2340 unfortunately not portable.
2344 To find things in a KDBX database, you should use a filtered iterator. If you have an iterator, such as
2345 returned by L</entries>, L</groups> or even L</objects> you can filter it using L<File::KDBX::Iterator/where>.
2347 my $filtered_entries = $kdbx->entries->where(\&query);
2349 A C<\&query> is just a subroutine that you can either write yourself or have generated for you from either
2350 a L</"Simple Expression"> or L</"Declarative Syntax">. It's easier to have your query generated, so I'll cover
2353 =head2 Simple Expression
2355 A simple expression is mostly compatible with the KeePass 2 implementation
2356 L<described here|https://keepass.info/help/base/search.html#mode_se>.
2358 An expression is a string with one or more space-separated terms. Terms with spaces can be enclosed in double
2359 quotes. Terms are negated if they are prefixed with a minus sign. A record must match every term on at least
2360 one of the given fields.
2362 So a simple expression is something like what you might type into a search engine. You can generate a simple
2363 expression query using L<File::KDBX::Util/simple_expression_query> or by passing the simple expression as
2364 a B<scalar reference> to C<where>.
2366 To search for all entries in a database with the word "canyon" appearing anywhere in the title:
2368 my $entries = $kdbx->entries->where(\'canyon', qw[title]);
2370 Notice the first argument is a B<scalarref>. This disambiguates a simple expression from other types of
2371 queries covered below.
2373 As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that
2374 has the words "red" B<and> "canyon" anywhere in the title:
2376 my $entries = $kdbx->entries->where(\'red canyon', qw[title]);
2378 Each term in the simple expression must be found for an entry to match.
2380 To search for entries with "red" in the title but B<not> "canyon", just prepend "canyon" with a minus sign:
2382 my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);
2384 To search over multiple fields simultaneously, just list them all. To search for entries with "grocery" (but
2385 not "Foodland") in the title or notes:
2387 my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);
2389 The default operator is a case-insensitive regexp match, which is fine for searching text loosely. You can use
2390 just about any binary comparison operator that perl supports. To specify an operator, list it after the simple
2391 expression. For example, to search for any entry that has been used at least five times:
2393 my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);
2395 It helps to read it right-to-left, like "usage_count is greater than or equal to 5".
2397 If you find the disambiguating structures to be distracting or confusing, you can also the
2398 L<File::KDBX::Util/simple_expression_query> function as a more intuitive alternative. The following example is
2399 equivalent to the previous:
2401 my $entries = $kdbx->entries->where(simple_expression_query(5, '>=', qw[usage_count]));
2403 =head2 Declarative Syntax
2405 Structuring a declarative query is similar to L<SQL::Abstract/"WHERE CLAUSES">, but you don't have to be
2406 familiar with that module. Just learn by examples here.
2408 To search for all entries in a database titled "My Bank":
2410 my $entries = $kdbx->entries->where({ title => 'My Bank' });
2412 The query here is C<< { title => 'My Bank' } >>. A hashref can contain key-value pairs where the key is an
2413 attribute of the thing being searched for (in this case an entry) and the value is what you want the thing's
2414 attribute to be to consider it a match. In this case, the attribute we're using as our match criteria is
2415 L<File::KDBX::Entry/title>, a text field. If an entry has its title attribute equal to "My Bank", it's
2418 A hashref can contain multiple attributes. The search candidate will be a match if I<all> of the specified
2419 attributes are equal to their respective values. For example, to search for all entries with a particular URL
2422 my $entries = $kdbx->entries->where({
2423 url => 'https://example.com',
2427 To search for entries matching I<any> criteria, just change the hashref to an arrayref. To search for entries
2428 with a particular URL B<OR> username:
2430 my $entries = $kdbx->entries->where([ # <-- Notice the square bracket
2431 url => 'https://example.com',
2435 You can use different operators to test different types of attributes. The L<File::KDBX::Entry/icon_id>
2436 attribute is a number, so we should use a number comparison operator. To find entries using the smartphone
2439 my $entries = $kdbx->entries->where({
2440 icon_id => { '==', ICON_SMARTPHONE },
2443 Note: L<File::KDBX::Constants/ICON_SMARTPHONE> is just a constant from L<File::KDBX::Constants>. It isn't
2444 special to this example or to queries generally. We could have just used a literal number.
2446 The important thing to notice here is how we wrapped the condition in another arrayref with a single key-value
2447 pair where the key is the name of an operator and the value is the thing to match against. The supported
2454 C<eq> - String equal
2458 C<ne> - String not equal
2462 C<lt> - String less than
2466 C<gt> - String greater than
2470 C<le> - String less than or equal
2474 C<ge> - String greater than or equal
2478 C<==> - Number equal
2482 C<!=> - Number not equal
2486 C<< < >> - Number less than
2490 C<< > >> - Number greater than
2494 C<< <= >> - Number less than or equal
2498 C<< >= >> - Number less than or equal
2502 C<=~> - String match regular expression
2506 C<!~> - String does not match regular expression
2510 C<!> - Boolean false
2514 C<!!> - Boolean true
2518 Other special operators:
2524 C<-true> - Boolean true
2528 C<-false> - Boolean false
2532 C<-not> - Boolean false (alias for C<-false>)
2536 C<-defined> - Is defined
2540 C<-undef> - Is not defined
2544 C<-empty> - Is empty
2548 C<-nonempty> - Is not empty
2556 C<-and> - Logical and
2560 Let's see another example using an explicit operator. To find all groups except one in particular (identified
2561 by its L<File::KDBX::Group/uuid>), we can use the C<ne> (string not equal) operator:
2563 my $groups = $kdbx->groups->where(
2565 'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
2569 Note: L<File::KDBX::Util/uuid> is a little utility function to convert a UUID in its pretty form into bytes.
2570 This utility function isn't special to this example or to queries generally. It could have been written with
2571 a literal such as C<"\x59\x6f\x75\x20\x61...">, but that's harder to read.
2573 Notice we searched for groups this time. Finding groups works exactly the same as it does for entries.
2575 Notice also that we didn't wrap the query in hashref curly-braces or arrayref square-braces. Those are
2576 optional. By default it will only match ALL attributes (as if there were curly-braces).
2578 Testing the truthiness of an attribute is a little bit different because it isn't a binary operation. To find
2579 all entries with the password quality check disabled:
2581 my $entries = $kdbx->entries->where('!' => 'quality_check');
2583 This time the string after the operator is the attribute name rather than a value to compare the attribute
2584 against. To test that a boolean value is true, use the C<!!> operator (or C<-true> if C<!!> seems a little too
2585 weird for your taste):
2587 my $entries = $kdbx->entries->where('!!' => 'quality_check');
2588 my $entries = $kdbx->entries->where(-true => 'quality_check'); # same thing
2590 Yes, there is also a C<-false> and a C<-not> if you prefer one of those over C<!>. C<-false> and C<-not>
2591 (along with C<-true>) are also special in that you can use them to invert the logic of a subquery. These are
2592 logically equivalent:
2594 my $entries = $kdbx->entries->where(-not => { title => 'My Bank' });
2595 my $entries = $kdbx->entries->where(title => { 'ne' => 'My Bank' });
2597 These special operators become more useful when combined with two more special operators: C<-and> and C<-or>.
2598 With these, it is possible to construct more interesting queries with groups of logic. For example:
2600 my $entries = $kdbx->entries->where({
2601 title => { '=~', qr/bank/ },
2604 notes => { '=~', qr/business/ },
2605 icon_id => { '==', ICON_TRASHCAN_FULL },
2610 In English, find entries where the word "bank" appears anywhere in the title but also do not have either the
2611 word "business" in the notes or are using the full trashcan icon.
2613 =head2 Subroutine Query
2615 Lastly, as mentioned at the top, you can ignore all this and write your own subroutine. Your subroutine will
2616 be called once for each object being searched over. The subroutine should match the candidate against whatever
2617 criteria you want and return true if it matches or false to skip. To do this, just pass your subroutine
2618 coderef to C<where>.
2620 To review the different types of queries, these are all equivalent to find all entries in the database titled
2623 my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]); # simple expression
2624 my $entries = $kdbx->entries->where(title => 'My Bank'); # declarative syntax
2625 my $entries = $kdbx->entries->where(sub { $_->title eq 'My Bank' }); # subroutine query
2627 This is a trivial example, but of course your subroutine can be arbitrarily complex.
2629 All of these query mechanisms described in this section are just tools, each with its own set of limitations.
2630 If the tools are getting in your way, you can of course iterate over the contents of a database and implement
2631 your own query logic, like this:
2633 my $entries = $kdbx->entries;
2634 while (my $entry = $entries->next) {
2635 if (wanted($entry)) {
2636 do_something($entry);
2645 Iterators are the built-in way to navigate or walk the database tree. You get an iterator from L</entries>,
2646 L</groups> and L</objects>. You can specify the search algorithm to iterate over objects in different orders
2647 using the C<algorithm> option, which can be one of these L<constants|File::KDBX::Constants/":iteration">:
2653 C<ITERATION_IDS> - Iterative deepening search (default)
2657 C<ITERATION_DFS> - Depth-first search
2661 C<ITERATION_BFS> - Breadth-first search
2665 When iterating over objects generically, groups always precede their direct entries (if any). When the
2666 C<history> option is used, current entries always precede historical entries.
2668 If you have a database tree like this:
2683 IDS order of groups is: Root, Group1, Group2, Group3
2687 IDS order of entries is: EntryA, EntryB, EntryC
2691 IDS order of objects is: Root, Group1, EntryA, Group2, EntryB, Group3, EntryC
2695 DFS order of groups is: Group2, Group1, Group3, Root
2699 DFS order of entries is: EntryB, EntryA, EntryC
2703 DFS order of objects is: Group2, EntryB, Group1, EntryA, Group3, EntryC, Root
2707 BFS order of groups is: Root, Group1, Group3, Group2
2711 BFS order of entries is: EntryA, EntryC, EntryB
2715 BFS order of objects is: Root, Group1, EntryA, Group3, EntryC, Group2, EntryB
2719 =head1 SYNCHRONIZING
2721 B<TODO> - This is a planned feature, not yet implemented.
2725 Errors in this package are constructed as L<File::KDBX::Error> objects and propagated using perl's built-in
2726 mechanisms. Fatal errors are propagated using L<perlfunc/"die LIST"> and non-fatal errors (a.k.a. warnings)
2727 are propagated using L<perlfunc/"warn LIST"> while adhering to perl's L<warnings> system. If you're already
2728 familiar with these mechanisms, you can skip this section.
2730 You can catch fatal errors using L<perlfunc/"eval BLOCK"> (or something like L<Try::Tiny>) and non-fatal
2731 errors using C<$SIG{__WARN__}> (see L<perlvar/%SIG>). Examples:
2733 use File::KDBX::Error qw(error);
2735 my $key = ''; # uh oh
2737 $kdbx->load_file('whatever.kdbx', $key);
2739 if (my $error = error($@)) {
2740 handle_missing_key($error) if $error->type eq 'key.missing';
2744 or using C<Try::Tiny>:
2747 $kdbx->load_file('whatever.kdbx', $key);
2753 Catching non-fatal errors:
2756 local $SIG{__WARN__} = sub { push @warnings, $_[0] };
2758 $kdbx->load_file('whatever.kdbx', $key);
2760 handle_warnings(@warnings) if @warnings;
2762 By default perl prints warnings to C<STDERR> if you don't catch them. If you don't want to catch them and also
2763 don't want them printed to C<STDERR>, you can suppress them lexically (perl v5.28 or higher required):
2766 no warnings 'File::KDBX';
2773 local $File::KDBX::WARNINGS = 0;
2777 or globally in your program:
2779 $File::KDBX::WARNINGS = 0;
2781 You cannot suppress fatal errors, and if you don't catch them your program will exit.
2785 This software will alter its behavior depending on the value of certain environment variables:
2791 C<PERL_FILE_KDBX_XS> - Do not use L<File::KDBX::XS> if false (default: true)
2795 C<PERL_ONLY> - Do not use L<File::KDBX::XS> if true (default: false)
2799 C<NO_FORK> - Do not fork if true (default: false)
2809 L<KeePass Password Safe|https://keepass.info/> - The original KeePass
2813 L<KeePassXC|https://keepassxc.org/> - Cross-Platform Password Manager written in C++
2817 L<File::KeePass> has overlapping functionality. It's good but has a backlog of some pretty critical bugs and lacks support for newer KDBX features.
2823 Please report any bugs or feature requests on the bugtracker website
2824 L<https://github.com/chazmcgarvey/File-KDBX/issues>
2826 When submitting a bug or request, please include a test-file or a
2827 patch to an existing test-file that illustrates the bug or desired
2832 Charles McGarvey <ccm@cpan.org>
2834 =head1 COPYRIGHT AND LICENSE
2836 This software is copyright (c) 2022 by Charles McGarvey.
2838 This is free software; you can redistribute it and/or modify it under
2839 the same terms as the Perl 5 programming language system itself.