2 # ABSTRACT: Encrypted databases to store secret text and files
7 use Crypt
::PRNG
qw(random_bytes);
8 use Devel
::GlobalDestruction
;
9 use File
::KDBX
::Constants
qw(:all);
10 use File
::KDBX
::Error
;
12 use File
::KDBX
::Util
qw(:empty erase generate_uuid search simple_expression_query snakify);
13 use Hash
::Util
::FieldHash
qw(fieldhashes);
14 use List
::Util
qw(any);
15 use Ref
::Util
qw(is_ref is_arrayref is_plain_hashref);
16 use Scalar
::Util
qw(blessed);
21 our $VERSION = '999.999'; # VERSION
24 fieldhashes \
my (%SAFE, %KEYS);
28 $kdbx = File
::KDBX-
>new(%attributes);
29 $kdbx = File
::KDBX-
>new($kdbx); # copy constructor
31 Construct a new L
<File
::KDBX
>.
39 return $_[0]->clone if @_ == 1 && blessed
$_[0] && $_[0]->isa($class);
41 my $self = bless {}, $class;
43 $self->_set_default_attributes if empty
$self;
47 sub DESTROY
{ local ($., $@, $!, $^E, $?); !in_global_destruction
and $_[0]->reset }
51 $kdbx = $kdbx->init(%attributes);
53 Initialize a L
<File
::KDBX
> with a new set of attributes
. Returns itself to allow
method chaining
.
55 This
is called by L
</new
>.
63 @$self{keys %args} = values %args;
72 Set a L
<File
::KDBX
> to an empty
state, ready to load a KDBX file
or build a new one
. Returns itself to allow
79 erase
$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY
};
80 erase
$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY
};
89 $kdbx_copy = $kdbx->clone;
90 $kdbx_copy = File
::KDBX-
>new($kdbx);
92 Clone a L
<File
::KDBX
>. The clone will be an exact copy
and completely independent of the original
.
99 return Storable
::dclone
($self);
102 sub STORABLE_freeze
{
108 return '', $copy, $KEYS{$self} // (), $SAFE{$self} // ();
119 @$self{keys %$clone} = values %$clone;
121 $SAFE{$self} = $safe;
123 for my $object (@{$self->all_groups}, @{$self->all_entries(history
=> 1)}) {
124 $object->kdbx($self);
128 ##############################################################################
138 $kdbx = KDBX
::File-
>load(\
$string, $key);
139 $kdbx = KDBX
::File-
>load(*IO
, $key);
140 $kdbx = KDBX
::File-
>load($filepath, $key);
141 $kdbx->load(...); # also instance method
143 $kdbx = File
::KDBX-
>load_string($string, $key);
144 $kdbx = File
::KDBX-
>load_string(\
$string, $key);
145 $kdbx->load_string(...); # also instance method
147 $kdbx = File
::KDBX-
>load_file($filepath, $key);
148 $kdbx->load_file(...); # also instance method
150 $kdbx = File
::KDBX-
>load_handle($fh, $key);
151 $kdbx = File
::KDBX-
>load_handle(*IO
, $key);
152 $kdbx->load_handle(...); # also instance method
154 Load a KDBX file from a string buffer
, IO handle
or file from a filesystem
.
156 L
<File
::KDBX
::Loader
> does the heavy lifting
.
160 sub load
{ shift-
>_loader->load(@_) }
161 sub load_string
{ shift-
>_loader->load_string(@_) }
162 sub load_file
{ shift-
>_loader->load_file(@_) }
163 sub load_handle
{ shift-
>_loader->load_handle(@_) }
167 $self = $self->new if !ref $self;
168 require File
::KDBX
::Loader
;
169 File
::KDBX
::Loader-
>new(kdbx
=> $self);
180 $kdbx->dump(\
$string, $key);
181 $kdbx->dump(*IO
, $key);
182 $kdbx->dump($filepath, $key);
184 $kdbx->dump_string(\
$string, $key);
185 \
$string = $kdbx->dump_string($key);
187 $kdbx->dump_file($filepath, $key);
189 $kdbx->dump_handle($fh, $key);
190 $kdbx->dump_handle(*IO
, $key);
192 Dump a KDBX file to a string buffer
, IO handle
or file
in a filesystem
.
194 L
<File
::KDBX
::Dumper
> does the heavy lifting
.
198 sub dump { shift-
>_dumper->dump(@_) }
199 sub dump_string
{ shift-
>_dumper->dump_string(@_) }
200 sub dump_file
{ shift-
>_dumper->dump_file(@_) }
201 sub dump_handle
{ shift-
>_dumper->dump_handle(@_) }
205 $self = $self->new if !ref $self;
206 require File
::KDBX
::Dumper
;
207 File
::KDBX
::Dumper-
>new(kdbx
=> $self);
210 ##############################################################################
212 =method user_agent_string
214 $string = $kdbx->user_agent_string;
216 Get a text string identifying the database client software
.
220 sub user_agent_string
{
222 sprintf('%s/%s (%s/%s; %s/%s; %s)',
223 __PACKAGE__
, $VERSION, @Config::Config
{qw(package version osname osvers archname)});
240 =attr deleted_objects
244 $value = $kdbx->$attr;
245 $kdbx->$attr($value);
247 Get
and set attributes
.
254 version
=> KDBX_VERSION_3_1
,
255 headers
=> sub { +{} },
256 inner_headers
=> sub { +{} },
258 binaries
=> sub { +{} },
259 deleted_objects
=> sub { +{} },
262 my %ATTRS_HEADERS = (
263 HEADER_COMMENT
() => '',
264 HEADER_CIPHER_ID
() => CIPHER_UUID_CHACHA20
,
265 HEADER_COMPRESSION_FLAGS
() => COMPRESSION_GZIP
,
266 HEADER_MASTER_SEED
() => sub { random_bytes
(32) },
267 # HEADER_TRANSFORM_SEED() => sub { random_bytes(32) },
268 # HEADER_TRANSFORM_ROUNDS() => 100_000,
269 HEADER_ENCRYPTION_IV
() => sub { random_bytes
(16) },
270 # HEADER_INNER_RANDOM_STREAM_KEY() => sub { random_bytes(32) }, # 64?
271 HEADER_STREAM_START_BYTES
() => sub { random_bytes
(32) },
272 # HEADER_INNER_RANDOM_STREAM_ID() => STREAM_ID_CHACHA20,
273 HEADER_KDF_PARAMETERS
() => sub {
275 KDF_PARAM_UUID
() => KDF_UUID_AES
,
276 KDF_PARAM_AES_ROUNDS
() => $_[0]->headers->{+HEADER_TRANSFORM_ROUNDS
} // KDF_DEFAULT_AES_ROUNDS
,
277 KDF_PARAM_AES_SEED
() => $_[0]->headers->{+HEADER_TRANSFORM_SEED
} // random_bytes
(32),
280 # HEADER_PUBLIC_CUSTOM_DATA() => sub { +{} },
286 database_name_changed
=> sub { gmtime },
287 database_description
=> '',
288 database_description_changed
=> sub { gmtime },
289 default_username
=> '',
290 default_username_changed
=> sub { gmtime },
291 maintenance_history_days
=> 0,
293 master_key_changed
=> sub { gmtime },
294 master_key_change_rec
=> -1,
295 master_key_change_force
=> -1,
296 # memory_protection => sub { +{} },
297 custom_icons
=> sub { +{} },
298 recycle_bin_enabled
=> true
,
299 recycle_bin_uuid
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
300 recycle_bin_changed
=> sub { gmtime },
301 entry_templates_group
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
302 entry_templates_group_changed
=> sub { gmtime },
303 last_selected_group
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
304 last_top_visible_group
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
305 history_max_items
=> HISTORY_DEFAULT_MAX_ITEMS
,
306 history_max_size
=> HISTORY_DEFAULT_MAX_SIZE
,
307 settings_changed
=> sub { gmtime },
308 # binaries => sub { +{} },
309 # custom_data => sub { +{} },
311 my %ATTRS_MEMORY_PROTECTION = (
312 protect_title
=> false
,
313 protect_username
=> false
,
314 protect_password
=> true
,
315 protect_url
=> false
,
316 protect_notes
=> false
,
317 auto_enable_visual_hiding
=> false
,
320 sub _update_group_uuid
{
322 my $old_uuid = shift // return;
323 my $new_uuid = shift;
325 my $meta = $self->meta;
326 $self->recycle_bin_uuid($new_uuid) if $old_uuid eq ($meta->{recycle_bin_uuid
} // '');
327 $self->entry_templates_group($new_uuid) if $old_uuid eq ($meta->{entry_templates_group
} // '');
328 $self->last_selected_group($new_uuid) if $old_uuid eq ($meta->{last_selected_group
} // '');
329 $self->last_top_visible_group($new_uuid) if $old_uuid eq ($meta->{last_top_visible_group
} // '');
331 for my $group (@{$self->all_groups}) {
332 $group->last_top_visible_entry($new_uuid) if $old_uuid eq ($group->{last_top_visible_entry
} // '');
333 $group->previous_parent_group($new_uuid) if $old_uuid eq ($group->{previous_parent_group
} // '');
335 for my $entry (@{$self->all_entries}) {
336 $entry->previous_parent_group($new_uuid) if $old_uuid eq ($entry->{previous_parent_group
} // '');
340 sub _update_entry_uuid
{
342 my $old_uuid = shift // return;
343 my $new_uuid = shift;
345 for my $entry (@{$self->all_entries}) {
346 $entry->previous_parent_group($new_uuid) if $old_uuid eq ($entry->{previous_parent_group
} // '');
350 while (my ($attr, $default) = each %ATTRS) {
351 no strict
'refs'; ## no critic (ProhibitNoStrict)
354 $self->{$attr} = shift if @_;
355 $self->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
358 while (my ($attr, $default) = each %ATTRS_HEADERS) {
359 no strict
'refs'; ## no critic (ProhibitNoStrict)
362 $self->headers->{$attr} = shift if @_;
363 $self->headers->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
366 while (my ($attr, $default) = each %ATTRS_META) {
367 no strict
'refs'; ## no critic (ProhibitNoStrict)
370 $self->meta->{$attr} = shift if @_;
371 $self->meta->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
374 while (my ($attr, $default) = each %ATTRS_MEMORY_PROTECTION) {
375 no strict
'refs'; ## no critic (ProhibitNoStrict)
378 $self->meta->{$attr} = shift if @_;
379 $self->meta->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
384 HEADER_TRANSFORM_SEED
,
385 HEADER_TRANSFORM_ROUNDS
,
386 HEADER_INNER_RANDOM_STREAM_KEY
,
387 HEADER_INNER_RANDOM_STREAM_ID
,
389 sub _set_default_attributes
{
391 $self->$_ for keys %ATTRS, keys %ATTRS_HEADERS, keys %ATTRS_META, keys %ATTRS_MEMORY_PROTECTION,
395 =method memory_protection
397 \
%settings = $kdbx->memory_protection
398 $kdbx->memory_protection(\
%settings);
400 $bool = $kdbx->memory_protection($string_key);
401 $kdbx->memory_protection($string_key => $bool);
403 Get
or set memory protection settings
. This globally
(for the whole database
) configures whether
and which of
404 the standard strings should be memory-protected
. The
default setting
is to memory-protect only I
<Password
>
407 Memory protection can be toggled individually
for each entry string
, and individual settings
take precedence
408 over these global settings
.
412 sub memory_protection
{
414 $self->{meta
}{memory_protection
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
415 return $self->{meta
}{memory_protection
} //= {} if !@_;
417 my $string_key = shift;
418 my $key = 'protect_' . lc($string_key);
420 $self->meta->{memory_protection
}{$key} = shift if @_;
421 $self->meta->{memory_protection
}{$key};
424 =method minimum_version
426 $version = $kdbx->minimum_version;
428 Determine the minimum file version required to save a database losslessly
. Using certain databases features
429 might increase this value
. For example
, setting the KDF to Argon2 will increase the minimum version to at
430 least C
<KDBX_VERSION_4_0
> (i
.e
. C
<0x00040000>) because Argon2 was introduced with KDBX4
.
432 This
method never returns less than C
<KDBX_VERSION_3_1
> (i
.e
. C
<0x00030001>). That file version
is so
433 ubiquitious
and well-supported
, there are seldom reasons to
dump in a lesser format nowadays
.
435 B
<WARNING
:> If you
dump a database with a minimum version higher than the current L
</version
>, the dumper will
436 typically issue a warning
and automatically upgrade the database
. This seems like the safest behavior
in order
437 to avoid data loss
, but lower versions have the benefit of being compatible with more software
. It
is possible
438 to prevent auto-upgrades by explicitly telling the dumper which version to
use, but you
do run the risk of
439 data loss
. A database will never be automatically downgraded
.
443 sub minimum_version
{
446 return KDBX_VERSION_4_1
if any
{
447 nonempty
$_->{last_modification_time
}
448 } values %{$self->custom_data};
450 return KDBX_VERSION_4_1
if any
{
451 nonempty
$_->{name
} || nonempty
$_->{last_modification_time
}
452 } values %{$self->custom_icons};
454 return KDBX_VERSION_4_1
if any
{
455 nonempty
$_->previous_parent_group || nonempty
$_->tags ||
456 any
{ nonempty
$_->{last_modification_time
} } values %{$_->custom_data}
457 } @{$self->all_groups};
459 return KDBX_VERSION_4_1
if any
{
460 nonempty
$_->previous_parent_group || (defined $_->quality_check && !$_->quality_check) ||
461 any
{ nonempty
$_->{last_modification_time
} } values %{$_->custom_data}
462 } @{$self->all_entries(history
=> 1)};
464 return KDBX_VERSION_4_0
if $self->kdf->uuid ne KDF_UUID_AES
;
466 return KDBX_VERSION_4_0
if nonempty
$self->public_custom_data;
468 return KDBX_VERSION_4_0
if any
{
469 nonempty
$_->custom_data
470 } @{$self->all_groups}, @{$self->all_entries(history
=> 1)};
472 return KDBX_VERSION_3_1
;
475 ##############################################################################
479 $kdbx->add_group($group, %options);
480 $kdbx->add_group(%group_attributes, %options);
482 Add a group to a database
. This
is equivalent to identifying a parent group
and calling
483 L
<File
::KDBX
::Group
/add_group
> on the parent group
, forwarding the arguments
. Available options
:
486 * C<group> (aka C<parent>) - Group (object or group UUID) to add the group to (default: root group)
492 my $group = @_ % 2 == 1 ? shift : undef;
495 # find the right group to add the group to
496 my $parent = delete $args{group
} // delete $args{parent
} // $self->root;
497 ($parent) = $self->find_groups({uuid
=> $parent}) if !ref $parent;
498 $parent or throw
'Invalid group';
500 return $parent->add_group(defined $group ? $group : (), %args, kdbx
=> $self);
506 require File
::KDBX
::Group
;
507 return File
::KDBX
::Group-
>wrap($group, $self);
512 $group = $kdbx->root;
515 Get
or set a database
's root group. You don't necessarily need to explicitly create
or set a root group
516 because it autovivifies
when adding entries
and groups to the database
.
518 Every database
has only a single root group at a
time. Some old KDB files might have multiple root groups
.
519 When reading such files
, a single implicit root group
is created to contain the other explicit groups
. When
520 writing to such a format
, if the root group looks like it was implicitly created then it won
't be written and
521 the resulting file might have multiple root groups. This allows working with older files without changing
522 their written internal structure while still adhering to the modern restrictions while the database is opened.
524 B<WARNING:> The root group of a KDBX database contains all of the database's entries
and other groups
. If you
525 replace the root group
, you are essentially replacing the entire database contents with something
else.
532 $self->{root
} = $self->_wrap_group(@_);
533 $self->{root
}->kdbx($self);
535 $self->{root
} //= $self->_implicit_root;
536 return $self->_wrap_group($self->{root
});
541 return [] if !$self->{root
};
542 return $self->_has_implicit_root ? $self->root->groups : [$self->root];
545 sub _has_implicit_root
{
547 my $root = $self->root;
548 my $temp = __PACKAGE__-
>_implicit_root;
549 # If an implicit root group has been changed in any significant way, it is no longer implicit.
550 return $root->name eq $temp->name &&
551 $root->is_expanded ^ $temp->is_expanded &&
552 $root->notes eq $temp->notes &&
553 !@{$root->entries} &&
554 !defined $root->custom_icon_uuid &&
555 !keys %{$root->custom_data} &&
556 $root->icon_id == $temp->icon_id &&
557 $root->expires ^ $temp->expires &&
558 $root->default_auto_type_sequence eq $temp->default_auto_type_sequence &&
559 !defined $root->enable_auto_type &&
560 !defined $root->enable_searching;
565 require File
::KDBX
::Group
;
566 return File
::KDBX
::Group-
>new(
569 notes
=> 'Added as an implicit root group by '.__PACKAGE__
.'.',
570 ref $self ? (kdbx
=> $self) : (),
576 \
@groups = $kdbx->all_groups(%options);
577 \
@groups = $kdbx->all_groups($base_group, %options);
579 Get all groups deeply
in a database
, or all groups within a specified base group
, in a flat array
. Supported
583 * C<base> - Only include groups within a base group (same as C<$base_group>) (default: root)
584 * C<include_base> - Include the base group in the results (default: true)
590 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
591 my $base = $args{base
} // $self->root;
593 my @groups = $args{include_base
} // 1 ? $self->_wrap_group($base) : ();
595 for my $subgroup (@{$base->{groups
} || []}) {
596 my $more = $self->all_groups($subgroup);
597 push @groups, @$more;
603 =method trace_lineage
605 \
@lineage = $kdbx->trace_lineage($group);
606 \
@lineage = $kdbx->trace_lineage($group, $base_group);
607 \
@lineage = $kdbx->trace_lineage($entry);
608 \
@lineage = $kdbx->trace_lineage($entry, $base_group);
610 Get the direct line of ancestors from C
<$base_group> (default: the root group
) to a group
or entry
. The
611 lineage includes the base group but I
<not> the target group
or entry
. Returns C
<undef> if the target
is not in
612 the database structure
.
619 return $object->lineage(@_);
627 push @lineage, $self->root if !@lineage;
628 my $base = $lineage[-1] or return [];
630 my $uuid = $object->uuid;
631 return \
@lineage if any
{ $_->uuid eq $uuid } @{$base->groups || []}, @{$base->entries || []};
633 for my $subgroup (@{$base->groups || []}) {
634 my $result = $self->_trace_lineage($object, @lineage, $subgroup);
635 return $result if $result;
641 @groups = $kdbx->find_groups($query, %options);
643 Find all groups deeply that match to a query
. Options are the same as
for L
</all_groups
>.
645 See L
</QUERY
> for a description of what C
<$query> can be
.
651 my $query = shift or throw
'Must provide a query';
655 include_base
=> $args{include_base
},
657 return @{search
($self->all_groups(%all_groups), is_arrayref
($query) ? @$query : $query)};
665 ##############################################################################
669 $kdbx->add_entry($entry, %options);
670 $kdbx->add_entry(%entry_attributes, %options);
672 Add a entry to a database
. This
is equivalent to identifying a parent group
and calling
673 L
<File
::KDBX
::Group
/add_entry
> on the parent group
, forwarding the arguments
. Available options
:
676 * C<group> (aka C<parent>) - Group (object or group UUID) to add the entry to (default: root group)
682 my $entry = @_ % 2 == 1 ? shift : undef;
685 # find the right group to add the entry to
686 my $parent = delete $args{group
} // delete $args{parent
} // $self->root;
687 ($parent) = $self->find_groups({uuid
=> $parent}) if !ref $parent;
688 $parent or throw
'Invalid group';
690 return $parent->add_entry(defined $entry ? $entry : (), %args, kdbx
=> $self);
696 require File
::KDBX
::Entry
;
697 return File
::KDBX
::Entry-
>wrap($entry, $self);
702 \
@entries = $kdbx->all_entries(%options);
703 \
@entries = $kdbx->all_entries($base_group, %options);
705 Get entries deeply
in a database
, in a flat array
. Supported options
:
708 * C<base> - Only include entries within a base group (same as C<$base_group>) (default: root)
709 * C<auto_type> - Only include entries with auto-type enabled (default: false, include all)
710 * C<search> - Only include entries within groups with search enabled (default: false, include all)
711 * C<history> - Also include historical entries (default: false, include only active entries)
717 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
719 my $base = $args{base
} // $self->root;
720 my $history = $args{history
};
721 my $search = $args{search
};
722 my $auto_type = $args{auto_type
};
724 my $enable_auto_type = $base->{enable_auto_type
} // true
;
725 my $enable_searching = $base->{enable_searching
} // true
;
728 if ((!$search || $enable_searching) && (!$auto_type || $enable_auto_type)) {
730 map { $self->_wrap_entry($_) }
731 grep { !$auto_type || $_->{auto_type
}{enabled
} }
732 map { $_, $history ? @{$_->{history
} || []} : () }
733 @{$base->{entries
} || []};
736 for my $subgroup (@{$base->{groups
} || []}) {
737 my $more = $self->all_entries($subgroup,
738 auto_type
=> $auto_type,
742 push @entries, @$more;
750 =method find_entries_simple
752 @entries = $kdbx->find_entries($query, %options);
754 @entries = $kdbx->find_entries_simple($expression, \
@fields, %options);
755 @entries = $kdbx->find_entries_simple($expression, $operator, \
@fields, %options);
757 Find all entries deeply that match a query
. Options are the same as
for L
</all_entries
>.
759 See L
</QUERY
> for a description of what C
<$query> can be
.
765 my $query = shift or throw
'Must provide a query';
769 auto_type
=> $args{auto_type
},
770 search
=> $args{search
},
771 history
=> $args{history
},
773 return @{search
($self->all_entries(%all_entries), is_arrayref
($query) ? @$query : $query)};
776 sub find_entries_simple
{
779 my $op = @_ && !is_ref
($_[0]) ? shift : undef;
781 is_arrayref
($fields) or throw
q{Usage: find_entries_simple($expression, [$op,] \@fields)};
782 return $self->find_entries([\
$text, $op, $fields], @_);
785 ##############################################################################
789 \
%icon = $kdbx->custom_icon($uuid);
790 $kdbx->custom_icon($uuid => \
%icon);
791 $kdbx->custom_icon(%icon);
792 $kdbx->custom_icon(uuid
=> $value, %icon);
799 my %args = @_ == 2 ? (uuid
=> shift, value
=> shift)
800 : @_ % 2 == 1 ? (uuid
=> shift, @_) : @_;
802 if (!$args{key
} && !$args{value
}) {
803 my %standard = (key
=> 1, value
=> 1, last_modification_time
=> 1);
804 my @other_keys = grep { !$standard{$_} } keys %args;
805 if (@other_keys == 1) {
806 my $key = $args{key
} = $other_keys[0];
807 $args{value
} = delete $args{$key};
811 my $key = $args{key
} or throw
'Must provide a custom_icons key to access';
813 return $self->{meta
}{custom_icons
}{$key} = $args{value
} if is_plain_hashref
($args{value
});
815 while (my ($field, $value) = each %args) {
816 $self->{meta
}{custom_icons
}{$key}{$field} = $value;
818 return $self->{meta
}{custom_icons
}{$key};
821 =method custom_icon_data
823 $image_data = $kdbx->custom_icon_data($uuid);
829 sub custom_icon_data
{
831 my $uuid = shift // return;
832 return if !exists $self->custom_icons->{$uuid};
833 return $self->custom_icons->{$uuid}{data
};
836 =method add_custom_icon
838 $uuid = $kdbx->add_custom_icon($image_data, %attributes);
840 Add a custom icon
and get its UUID
. If
not provided
, a random UUID will be generated
. Possible attributes
:
843 * C<uuid> - Icon UUID
844 * C<name> - Name of the icon (text, KDBX4.1+)
845 * C<last_modification_time> - Just what it says (datetime, KDBX4.1+)
849 sub add_custom_icon
{
851 my $img = shift or throw
'Must provide image data';
854 my $uuid = $args{uuid
} // generate_uuid
(sub { !$self->custom_icons->{$_} });
855 $self->custom_icons->{$uuid} = {
863 =method remove_custom_icon
865 $kdbx->remove_custom_icon($uuid);
867 Remove a custom icon
.
871 sub remove_custom_icon
{
874 delete $self->custom_icons->{$uuid};
877 ##############################################################################
881 \
%all_data = $kdbx->custom_data;
882 $kdbx->custom_data(\
%all_data);
884 \
%data = $kdbx->custom_data($key);
885 $kdbx->custom_data($key => \
%data);
886 $kdbx->custom_data(%data);
887 $kdbx->custom_data(key
=> $value, %data);
889 Get
and set custom data
. Custom data
is metadata associated with a database
.
891 Each data item can have a few attributes associated with it
.
894 * C<key> - A unique text string identifier used to look up the data item (required)
895 * C<value> - A text string value (required)
896 * C<last_modification_time> (optional, KDBX4.1+)
902 $self->{meta
}{custom_data
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
903 return $self->{meta
}{custom_data
} //= {} if !@_;
905 my %args = @_ == 2 ? (key
=> shift, value
=> shift)
906 : @_ % 2 == 1 ? (key
=> shift, @_) : @_;
908 if (!$args{key
} && !$args{value
}) {
909 my %standard = (key
=> 1, value
=> 1, last_modification_time
=> 1);
910 my @other_keys = grep { !$standard{$_} } keys %args;
911 if (@other_keys == 1) {
912 my $key = $args{key
} = $other_keys[0];
913 $args{value
} = delete $args{$key};
917 my $key = $args{key
} or throw
'Must provide a custom_data key to access';
919 return $self->{meta
}{custom_data
}{$key} = $args{value
} if is_plain_hashref
($args{value
});
921 while (my ($field, $value) = each %args) {
922 $self->{meta
}{custom_data
}{$key}{$field} = $value;
924 return $self->{meta
}{custom_data
}{$key};
927 =method custom_data_value
929 $value = $kdbx->custom_data_value($key);
931 Exactly the same as L
</custom_data
> except returns just the custom data
's value rather than a structure of
932 attributes. This is a shortcut for:
934 my $data = $kdbx->custom_data($key);
935 my $value = defined $data ? $data->{value} : undef;
939 sub custom_data_value {
941 my $data = $self->custom_data(@_) // return;
942 return $data->{value};
945 =method public_custom_data
947 \%all_data = $kdbx->public_custom_data;
948 $kdbx->public_custom_data(\%all_data);
950 $value = $kdbx->public_custom_data($key);
951 $kdbx->public_custom_data($key => $value);
953 Get and set public custom data. Public custom data is similar to custom data but different in some important
954 ways. Public custom data:
957 * can store strings, booleans and up to 64-bit integer values (custom data can only store text values)
958 * is NOT encrypted within a KDBX file (hence the "public" part of the name)
959 * is a flat hash/dict of key-value pairs (no other associated fields like modification times)
963 sub public_custom_data {
965 $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA} = shift if @_ == 1 && is_plain_hashref($_[0]);
966 return $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA} //= {} if !@_;
968 my $key = shift or throw 'Must provide a public_custom_data key to access
';
969 $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA}{$key} = shift if @_;
970 return $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA}{$key};
973 ##############################################################################
980 # my %options = @_; # prefer_old / prefer_new
981 # $other->merge_from($self);
988 # die 'Not implemented
';
991 ##############################################################################
993 =method resolve_reference
995 $string = $kdbx->resolve_reference($reference);
996 $string = $kdbx->resolve_reference($wanted, $search_in, $expression);
998 Resolve a L<field reference|https://keepass.info/help/base/fieldrefs.html>. A field reference is a kind of
999 string placeholder. You can use a field reference to refer directly to a standard field within an entry. Field
1000 references are resolved automatically while expanding entry strings (i.e. replacing placeholders), but you can
1001 use this method to resolve on-the-fly references that aren't part of any actual string
in the database
.
1003 If the reference
does not resolve to any field
, C
<undef> is returned
. If the reference resolves to multiple
1004 fields
, only the first one
is returned
(in the same order as L
</all_entries
>). To avoid ambiguity
, you can
1005 refer to a specific entry by its UUID
.
1007 The syntax of a reference
is: C
<< {REF
:<WantedField
>@<SearchIn
>:<Text
>} >>. C
<Text
> is a
1008 L
</"Simple Expression">. C
<WantedField
> and C
<SearchIn
> are both single character codes representing a field
:
1017 * C<O> - Other custom strings
1019 Since C<O> does not represent any specific field, it cannot be used as the C<WantedField>.
1023 To get the value of the I<UserName> string of the first entry with "My Bank" in the title:
1025 my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
1026 # OR the {REF:...} wrapper is optional
1027 my $username = $kdbx->resolve_reference('U@T:"My Bank"');
1028 # OR separate the arguments
1029 my $username = $kdbx->resolve_reference(U => T => '"My Bank"');
1031 Note how the text is a L</"Simple Expression">, so search terms with spaces must be surrounded in double
1034 To get the I<Password> string of a specific entry (identified by its UUID):
1036 my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');
1040 sub resolve_reference
{
1042 my $wanted = shift // return;
1043 my $search_in = shift;
1046 if (!defined $text) {
1047 $wanted =~ s/^\{REF:([^\}]+)\}$/$1/i;
1048 ($wanted, $search_in, $text) = $wanted =~ /^([TUPANI])\@([TUPANIO]):(.*)$/i;
1050 $wanted && $search_in && nonempty
($text) or return;
1053 T
=> 'expanded_title',
1054 U
=> 'expanded_username',
1055 P
=> 'expanded_password',
1056 A
=> 'expanded_url',
1057 N
=> 'expanded_notes',
1059 O
=> 'other_strings',
1061 $wanted = $fields{$wanted} or return;
1062 $search_in = $fields{$search_in} or return;
1064 my $query = simple_expression_query
($text, ($search_in eq 'id' ? 'eq' : '=~'), $search_in);
1066 my ($entry) = $self->find_entries($query);
1069 return $entry->$wanted;
1072 our %PLACEHOLDERS = (
1073 # placeholder => sub { my ($entry, $arg) = @_; ... };
1074 'TITLE' => sub { $_[0]->expanded_title },
1075 'USERNAME' => sub { $_[0]->expanded_username },
1076 'PASSWORD' => sub { $_[0]->expanded_password },
1077 'NOTES' => sub { $_[0]->expanded_notes },
1078 'S:' => sub { $_[0]->string_value($_[1]) },
1079 'URL' => sub { $_[0]->expanded_url },
1080 'URL:RMVSCM' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
1081 'URL:WITHOUTSCHEME' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
1082 'URL:SCM' => sub { (split_url
($_[0]->url))[0] },
1083 'URL:SCHEME' => sub { (split_url
($_[0]->url))[0] }, # non-standard
1084 'URL:HOST' => sub { (split_url
($_[0]->url))[2] },
1085 'URL:PORT' => sub { (split_url
($_[0]->url))[3] },
1086 'URL:PATH' => sub { (split_url
($_[0]->url))[4] },
1087 'URL:QUERY' => sub { (split_url
($_[0]->url))[5] },
1088 'URL:HASH' => sub { (split_url
($_[0]->url))[6] }, # non-standard
1089 'URL:FRAGMENT' => sub { (split_url
($_[0]->url))[6] }, # non-standard
1090 'URL:USERINFO' => sub { (split_url
($_[0]->url))[1] },
1091 'URL:USERNAME' => sub { (split_url
($_[0]->url))[7] },
1092 'URL:PASSWORD' => sub { (split_url
($_[0]->url))[8] },
1093 'UUID' => sub { local $_ = format_uuid
($_[0]->uuid); s/-//g; $_ },
1094 'REF:' => sub { $_[0]->kdbx->resolve_reference($_[1]) },
1095 'INTERNETEXPLORER' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('iexplore') },
1096 'FIREFOX' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('firefox') },
1097 'GOOGLECHROME' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('google-chrome') },
1098 'OPERA' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('opera') },
1099 'SAFARI' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('safari') },
1100 'APPDIR' => sub { load_optional
('FindBin'); $FindBin::Bin
},
1101 'GROUP' => sub { my $p = $_[0]->parent; $p ? $p->name : undef },
1102 'GROUP_PATH' => sub { $_[0]->path },
1103 'GROUP_NOTES' => sub { my $p = $_[0]->parent; $p ? $p->notes : undef },
1112 'ENV:' => sub { $ENV{$_[1]} },
1113 'ENV_DIRSEP' => sub { load_optional
('File::Spec')->catfile('', '') },
1114 'ENV_PROGRAMFILES_X86' => sub { $ENV{'ProgramFiles(x86)'} || $ENV{'ProgramFiles'} },
1117 'DT_SIMPLE' => sub { localtime-
>strftime('%Y%m%d%H%M%S') },
1118 'DT_YEAR' => sub { localtime-
>strftime('%Y') },
1119 'DT_MONTH' => sub { localtime-
>strftime('%m') },
1120 'DT_DAY' => sub { localtime-
>strftime('%d') },
1121 'DT_HOUR' => sub { localtime-
>strftime('%H') },
1122 'DT_MINUTE' => sub { localtime-
>strftime('%M') },
1123 'DT_SECOND' => sub { localtime-
>strftime('%S') },
1124 'DT_UTC_SIMPLE' => sub { gmtime-
>strftime('%Y%m%d%H%M%S') },
1125 'DT_UTC_YEAR' => sub { gmtime-
>strftime('%Y') },
1126 'DT_UTC_MONTH' => sub { gmtime-
>strftime('%m') },
1127 'DT_UTC_DAY' => sub { gmtime-
>strftime('%d') },
1128 'DT_UTC_HOUR' => sub { gmtime-
>strftime('%H') },
1129 'DT_UTC_MINUTE' => sub { gmtime-
>strftime('%M') },
1130 'DT_UTC_SECOND' => sub { gmtime-
>strftime('%S') },
1137 'HMACOTP' => sub { $_[0]->hmac_otp },
1138 'TIMEOTP' => sub { $_[0]->time_otp },
1139 'C:' => sub { '' }, # comment
1147 ##############################################################################
1153 Encrypt all protected strings
in a database
. The encrypted strings are stored
in a L
<File
::KDBX
::Safe
>
1154 associated with the database
and the actual strings will be replaced with C
<undef> to indicate their protected
1155 state. Returns itself to allow
method chaining
.
1161 $SAFE{$self} = shift if @_;
1165 sub _remove_safe
{ delete $SAFE{$_[0]} }
1170 $self->_safe and return $self;
1174 my $entries = $self->all_entries(history
=> 1);
1175 for my $entry (@$entries) {
1176 push @strings, grep { $_->{protect
} } values %{$entry->{strings
} || {}};
1179 $self->_safe(File
::KDBX
::Safe-
>new(\
@strings));
1188 Decrypt all protected strings
in a database
, replacing C
<undef> placeholders with unprotected
values. Returns
1189 itself to allow
method chaining
.
1196 my $safe = $self->_safe or return;
1197 return $safe->peek($string);
1202 my $safe = $self->_safe or return $self;
1205 $self->_remove_safe;
1210 # sub unlock_scoped {
1212 # return if !$self->is_locked;
1213 # require Scope::Guard;
1214 # my $guard = Scope::Guard->new(sub { $self->lock });
1221 $bool = $kdbx->is_locked;
1223 Get whether
or not a database
's strings are memory-protected. If this is true, then some or all of the
1224 protected strings within the database will be unavailable (literally have C<undef> values) until L</unlock> is
1229 sub is_locked { $_[0]->_safe ? 1 : 0 }
1231 ##############################################################################
1233 =method randomize_seeds
1235 $kdbx->randomize_seeds;
1237 Set various keys, seeds and IVs to random values. These values are used by the cryptographic functions that
1238 secure the database when dumped. The attributes that will be randomized are:
1242 * L</inner_random_stream_key>
1244 * L</stream_start_bytes>
1245 * L</transform_seed>
1247 Randomizing these values has no effect on a loaded database. These are only used when a database is dumped.
1248 You normally do not need to call this method explicitly because the dumper does it explicitly by default.
1252 sub randomize_seeds {
1254 $self->encryption_iv(random_bytes(16));
1255 $self->inner_random_stream_key(random_bytes(64));
1256 $self->master_seed(random_bytes(32));
1257 $self->stream_start_bytes(random_bytes(32));
1258 $self->transform_seed(random_bytes(32));
1261 ##############################################################################
1266 $key = $kdbx->key($key);
1267 $key = $kdbx->key($primitive);
1269 Get or set a L<File::KDBX::Key>. This is the master key (i.e. a password or a key file that can decrypt
1270 a database). See L<File::KDBX::Key/new> for an explanation of what the primitive can be.
1272 You generally don't need to call this directly because you can provide the key directly to the loader
or
1273 dumper
when loading
or saving a KDBX file
.
1279 $KEYS{$self} = File
::KDBX
::Key-
>new(@_) if @_;
1283 =method composite_key
1285 $key = $kdbx->composite_key($key);
1286 $key = $kdbx->composite_key($primitive);
1288 Construct a L
<File
::KDBX
::Key
::Composite
> from a primitive
. See L
<File
::KDBX
::Key
/new
> for an explanation of
1289 what the primitive can be
. If the primitive
does not represent a composite key
, it will be wrapped
.
1291 You generally don
't need to call this directly. The parser and writer use it to transform a master key into
1292 a raw encryption key.
1298 require File::KDBX::Key::Composite;
1299 return File::KDBX::Key::Composite->new(@_);
1304 $kdf = $kdbx->kdf(%options);
1305 $kdf = $kdbx->kdf(\%parameters, %options);
1307 Get a L<File::KDBX::KDF> (key derivation function).
1312 * C<params> - KDF parameters, same as C<\%parameters> (default: value of L</kdf_parameters>)
1318 my %args = @_ % 2 == 1 ? (params => shift, @_) : @_;
1320 my $params = $args{params};
1321 my $compat = $args{compatible} // 1;
1323 $params //= $self->kdf_parameters;
1324 $params = {%{$params || {}}};
1326 if (empty $params || !defined $params->{+KDF_PARAM_UUID}) {
1327 $params->{+KDF_PARAM_UUID} = KDF_UUID_AES;
1329 if ($params->{+KDF_PARAM_UUID} eq KDF_UUID_AES) {
1330 # AES_CHALLENGE_RESPONSE is equivalent to AES if there are no challenge-response keys, and since
1331 # non-KeePassXC implementations don't support challenge-response
keys anyway
, there
's no problem with
1332 # always using AES_CHALLENGE_RESPONSE for all KDBX4+ databases.
1333 # For compatibility, we should not *write* AES_CHALLENGE_RESPONSE, but the dumper handles that.
1334 if ($self->version >= KDBX_VERSION_4_0) {
1335 $params->{+KDF_PARAM_UUID} = KDF_UUID_AES_CHALLENGE_RESPONSE;
1337 $params->{+KDF_PARAM_AES_SEED} //= $self->transform_seed;
1338 $params->{+KDF_PARAM_AES_ROUNDS} //= $self->transform_rounds;
1341 require File::KDBX::KDF;
1342 return File::KDBX::KDF->new(%$params);
1345 sub transform_seed {
1347 $self->headers->{+HEADER_TRANSFORM_SEED} =
1348 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_SEED} = shift if @_;
1349 $self->headers->{+HEADER_TRANSFORM_SEED} =
1350 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_SEED} //= random_bytes(32);
1353 sub transform_rounds {
1355 $self->headers->{+HEADER_TRANSFORM_ROUNDS} =
1356 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_ROUNDS} = shift if @_;
1357 $self->headers->{+HEADER_TRANSFORM_ROUNDS} =
1358 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_ROUNDS} //= 100_000;
1363 $cipher = $kdbx->cipher(key => $key);
1364 $cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);
1366 Get a L<File::KDBX::Cipher> capable of encrypting and decrypting the body of a database file.
1368 A key is required. This should be a raw encryption key made up of a fixed number of octets (depending on the
1369 cipher), not a L<File::KDBX::Key> or primitive.
1371 If not passed, the UUID comes from C<< $kdbx->headers->{cipher_id} >> and the encryption IV comes from
1372 C<< $kdbx->headers->{encryption_iv} >>.
1374 You generally don't need to call this directly
. The parser
and writer
use it to decrypt
and encrypt KDBX
1383 $args{uuid
} //= $self->headers->{+HEADER_CIPHER_ID
};
1384 $args{iv
} //= $self->headers->{+HEADER_ENCRYPTION_IV
};
1386 require File
::KDBX
::Cipher
;
1387 return File
::KDBX
::Cipher-
>new(%args);
1390 =method random_stream
1392 $cipher = $kdbx->random_stream;
1393 $cipher = $kdbx->random_stream(id
=> $stream_id, key
=> $key);
1395 Get a L
<File
::KDBX
::Cipher
::Stream
> for decrypting
and encrypting protected
values.
1397 If
not passed
, the ID
and encryption key comes from C
<< $kdbx->headers->{inner_random_stream_id
} >> and
1398 C
<< $kdbx->headers->{inner_random_stream_key
} >> (respectively
) for KDBX3 files
and from
1399 C
<< $kdbx->inner_headers->{inner_random_stream_key
} >> and
1400 C
<< $kdbx->inner_headers->{inner_random_stream_id
} >> (respectively
) for KDBX4 files
.
1402 You generally don
't need to call this directly. The parser and writer use it to scramble protected strings.
1410 $args{stream_id} //= delete $args{id} // $self->inner_random_stream_id;
1411 $args{key} //= $self->inner_random_stream_key;
1413 require File::KDBX::Cipher;
1414 File::KDBX::Cipher->new(%args);
1417 sub inner_random_stream_id {
1419 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID}
1420 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID} = shift if @_;
1421 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID}
1422 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID} //= do {
1423 my $version = $self->minimum_version;
1424 $version < KDBX_VERSION_4_0 ? STREAM_ID_SALSA20 : STREAM_ID_CHACHA20;
1428 sub inner_random_stream_key {
1431 # These are probably the same SvPV so erasing one will CoW, but erasing the second should do the
1433 erase \$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY};
1434 erase \$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY};
1435 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY}
1436 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY} = shift;
1438 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY}
1439 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY} //= random_bytes(64); # 32
1442 #########################################################################################
1445 # - Fixer tool. Can repair inconsistencies, including:
1446 # - Orphaned binaries... not really a thing anymore since we now distribute binaries amongst entries
1447 # - Unused custom icons (OFF, data loss)
1449 # - All data types are valid
1450 # - date times are correct
1452 # - All UUIDs refer to things that exist
1453 # - previous parent group
1455 # - last selected group
1456 # - last visible group
1457 # - Enforce history size limits (ON)
1458 # - Check headers/meta (ON)
1459 # - Duplicate deleted objects (ON)
1460 # - Duplicate window associations (OFF)
1461 # - Only one root group (ON)
1462 # - Header UUIDs match known ciphers/KDFs?
1465 #########################################################################################
1469 A text string associated with the database. Often unset.
1473 The UUID of a cipher used to encrypt the database when stored as a file.
1475 See L</File::KDBX::Cipher>.
1477 =attr compression_flags
1479 Configuration for whether or not and how the database gets compressed. See
1480 L<File::KDBX::Constants/":compression">.
1484 The master seed is a string of 32 random bytes that is used as salt in hashing the master key when loading
1485 and saving the database. If a challenge-response key is used in the master key, the master seed is also the
1488 The master seed I<should> be changed each time the database is saved to file.
1490 =attr transform_seed
1492 The transform seed is a string of 32 random bytes that is used in the key derivation function, either as the
1493 salt or the key (depending on the algorithm).
1495 The transform seed I<should> be changed each time the database is saved to file.
1497 =attr transform_rounds
1499 The number of rounds or iterations used in the key derivation function. Increasing this number makes loading
1500 and saving the database slower by design in order to make dictionary and brute force attacks more costly.
1504 The initialization vector used by the cipher.
1506 The encryption IV I<should> be changed each time the database is saved to file.
1508 =attr inner_random_stream_key
1510 The encryption key (possibly including the IV, depending on the cipher) used to encrypt the protected strings
1511 within the database.
1513 =attr stream_start_bytes
1515 A string of 32 random bytes written in the header and encrypted in the body. If the bytes do not match when
1516 loading a file then the wrong master key was used or the file is corrupt. Only KDBX 2 and KDBX 3 files use
1517 this. KDBX 4 files use an improved HMAC method to verify the master key and data integrity of the header and
1520 =attr inner_random_stream_id
1522 A number indicating the cipher algorithm used to encrypt the protected strings within the database, usually
1523 Salsa20 or ChaCha20. See L<File::KDBX::Constants/":random_stream">.
1525 =attr kdf_parameters
1527 A hash/dict of key-value pairs used to configure the key derivation function. This is the KDBX4+ way to
1528 configure the KDF, superceding L</transform_seed> and L</transform_rounds>.
1532 The name of the software used to generate the KDBX file.
1536 The header hash used to verify that the file header is not corrupt. (KDBX 2 - KDBX 3.1, removed KDBX 4.0)
1540 Name of the database.
1542 =attr database_name_changed
1544 Timestamp indicating when the database name was last changed.
1546 =attr database_description
1548 Description of the database
1550 =attr database_description_changed
1552 Timestamp indicating when the database description was last changed.
1554 =attr default_username
1556 When a new entry is created, the I<UserName> string will be populated with this value.
1558 =attr default_username_changed
1560 Timestamp indicating when the default username was last changed.
1562 =attr maintenance_history_days
1564 TODO... not really sure what this is. 😀
1568 A color associated with the database (in the form C<#ffffff> where "f" is a hexidecimal digit). Some agents
1569 use this to help users visually distinguish between different databases.
1571 =attr master_key_changed
1573 Timestamp indicating when the master key was last changed.
1575 =attr master_key_change_rec
1577 Number of days until the agent should prompt to recommend changing the master key.
1579 =attr master_key_change_force
1581 Number of days until the agent should prompt to force changing the master key.
1583 Note: This is purely advisory. It is up to the individual agent software to actually enforce it.
1584 C<File::KDBX> does NOT enforce it.
1586 =attr recycle_bin_enabled
1588 Boolean indicating whether removed groups and entries should go to a recycle bin or be immediately deleted.
1590 =attr recycle_bin_uuid
1592 The UUID of a group used to store thrown-away groups and entries.
1594 =attr recycle_bin_changed
1596 Timestamp indicating when the recycle bin was last changed.
1598 =attr entry_templates_group
1600 The UUID of a group containing template entries used when creating new entries.
1602 =attr entry_templates_group_changed
1604 Timestamp indicating when the entry templates group was last changed.
1606 =attr last_selected_group
1608 The UUID of the previously-selected group.
1610 =attr last_top_visible_group
1612 The UUID of the group visible at the top of the list.
1614 =attr history_max_items
1616 The maximum number of historical entries allowed to be saved for each entry.
1618 =attr history_max_size
1620 The maximum total size (in bytes) that each individual entry's history
is allowed to grow
.
1622 =attr settings_changed
1624 Timestamp indicating
when the database settings were
last updated
.
1628 Alias of the L
</memory_protection
> setting
for the I
<Title
> string
.
1630 =attr protect_username
1632 Alias of the L
</memory_protection
> setting
for the I
<UserName
> string
.
1634 =attr protect_password
1636 Alias of the L
</memory_protection
> setting
for the I
<Password
> string
.
1640 Alias of the L
</memory_protection
> setting
for the I
<URL
> string
.
1644 Alias of the L
</memory_protection
> setting
for the I
<Notes
> string
.
1648 #########################################################################################
1650 sub TO_JSON
{ +{%{$_[0]}} }
1655 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
1661 my $kdbx = File::KDBX->new;
1663 my $group = $kdbx->add_group(
1664 name => 'Passwords',
1667 my $entry = $group->add_entry(
1669 password => 's3cr3t',
1672 $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
1674 $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
1676 for my $entry (@{ $kdbx->all_entries }) {
1677 say 'Entry: ', $entry->title;
1682 B<File::KDBX> provides everything you need to work with a KDBX database. A KDBX database is a hierarchical
1683 object database which is commonly used to store secret information securely. It was developed for the KeePass
1684 password safe. See L</"KDBX Introduction"> for more information about KDBX.
1686 This module lets you query entries, create new entries, delete entries and modify entries. The distribution
1687 also includes various parsers and generators for serializing and persisting databases.
1689 This design of this software was influenced by the L<KeePassXC|https://github.com/keepassxreboot/keepassxc>
1690 implementation of KeePass as well as the L<File::KeePass> module. B<File::KeePass> is an alternative module
1691 that works well in most cases but has a small backlog of bugs and security issues and also does not work with
1692 newer KDBX version 4 files. If you're coming here from the B<File::KeePass> world, you might be interested in
1693 L<File::KeePass::KDBX> that is a drop-in replacement for B<File::KeePass> that uses B<File::KDBX> for storage.
1695 =head2 KDBX Introduction
1697 A KDBX database consists of a hierarchical I<group> of I<entries>. Entries can contain zero or more key-value
1698 pairs of I<strings> and zero or more I<binaries> (i.e. octet strings). Groups, entries, strings and binaries:
1699 that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is associated with each entry, group
1700 and the database as a whole.
1702 You can think of a KDBX database kind of like a file system, where groups are directories, entries are files,
1703 and strings and binaries make up a file's contents.
1705 Databases are typically persisted as a encrypted, compressed files. They are usually accessed directly (i.e.
1706 not over a network). The primary focus of this type of database is data security. It is ideal for storing
1707 relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as
1708 have the correct I<master key>. Even if the database file were to be "leaked" to the public Internet, it
1709 should be virtually impossible to crack with a strong key. See L</SECURITY> for an overview of security
1714 =head2 Create a new database
1716 my $kdbx = File::KDBX->new;
1718 my $group = $kdbx->add_group(name => 'Passwords);
1719 my $entry = $group->add_entry(
1720 title => 'WayneCorp',
1721 username => 'bwayne',
1722 password => 'iambatman',
1723 url => 'https://example.com/login'
1725 $entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');
1727 $kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');
1729 =head2 Read an existing database
1731 my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
1734 for my $entry (@{ $kdbx->all_entries }) {
1735 say 'Found password for ', $entry->title, ':';
1736 say ' Username: ', $entry->username;
1737 say ' Password: ', $entry->password;
1740 =head2 Search for entries
1742 my @entries = $kdbx->find_entries({
1743 title => 'WayneCorp',
1746 See L</QUERY> for many more query examples.
1748 =head2 Search for entries by auto-type window association
1750 my @entry_key_sequences = $kdbx->find_entries_for_window('WayneCorp - Mozilla Firefox');
1751 for my $pair (@entry_key_sequences) {
1752 my ($entry, $key_sequence) = @$pair;
1753 say 'Entry title: ', $entry->title, ', key sequence: ', $key_sequence;
1758 Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}
1762 One of the biggest threats to your database security is how easily the encryption key can be brute-forced.
1763 Strong brute-force protection depends on a couple factors:
1766 * Using unguessable passwords, passphrases and key files.
1767 * Using a brute-force resistent key derivation function.
1769 The first factor is up to you. This module does not enforce strong master keys. It is up to you to pick or
1770 generate strong keys.
1772 The KDBX format allows for the key derivation function to be tuned. The idea is that you want each single
1773 brute-foce attempt to be expensive (in terms of time, CPU usage or memory usage), so that making a lot of
1774 attempts (which would be required if you have a strong master key) gets I<really> expensive.
1776 How expensive you want to make each attempt is up to you and can depend on the application.
1778 This and other KDBX-related security issues are covered here more in depth:
1779 L<https://keepass.info/help/base/security.html>
1781 Here are other security risks you should be thinking about:
1785 This distribution uses the excellent L<CryptX> and L<Crypt::Argon2> packages to handle all crypto-related
1786 functions. As such, a lot of the security depends on the quality of these dependencies. Fortunately these
1787 modules are maintained and appear to have good track records.
1789 The KDBX format has evolved over time to incorporate improved security practices and cryptographic functions.
1790 This package uses the following functions for authentication, hashing, encryption and random number
1796 * Argon2d & Argon2id
1801 * Salsa20 & ChaCha20
1804 At the time of this writing, I am not aware of any successful attacks against any of these functions. These
1805 are among the most-analyzed and widely-adopted crypto functions available.
1807 The KDBX format allows the body cipher and key derivation function to be configured. If a flaw is discovered
1808 in one of these functions, you can hopefully just switch to a better function without needing to update this
1809 software. A later software release may phase out the use of any functions which are no longer secure.
1811 =head2 Memory Protection
1813 It is not a good idea to keep secret information unencrypted in system memory for longer than is needed. The
1814 address space of your program can generally be read by a user with elevated privileges on the system. If your
1815 system is memory-constrained or goes into a hibernation mode, the contents of your address space could be
1816 written to a disk where it might be persisted for long time.
1818 There might be system-level things you can do to reduce your risk, like using swap encryption and limiting
1819 system access to your program's address space while your program is running.
1821 B<File::KDBX> helps minimize (but not eliminate) risk by keeping secrets encrypted in memory until accessed
1822 and zeroing out memory that holds secrets after they're no longer needed, but it's not a silver bullet.
1824 For one thing, the encryption key is stored in the same address space. If core is dumped, the encryption key
1825 is available to be found out. But at least there is the chance that the encryption key and the encrypted
1826 secrets won't both be paged out while memory-constrained.
1828 Another problem is that some perls (somewhat notoriously) copy around memory behind the scenes willy nilly,
1829 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
1830 be impossible. The good news is that perls with SvPV copy-on-write (enabled by default beginning with perl
1831 5.20) are much better in this regard. With COW, it's mostly possible to know what operations will cause perl
1832 to copy the memory of a scalar string, and the number of copies will be significantly reduced. There is a unit
1833 test named F<t/memory-protection.t> in this distribution that can be run on POSIX systems to determine how
1834 well B<File::KDBX> memory protection is working.
1836 Memory protection also depends on how your application handles secrets. If your app code is handling scalar
1837 strings with secret information, it's up to you to make sure its memory is zeroed out when no longer needed.
1838 L<File::KDBX::Util/erase> et al. provide some tools to help accomplish this. Or if you're not too concerned
1839 about the risks memory protection is meant to mitigate, then maybe don't worry about it. The security policy
1840 of B<File::KDBX> is to try hard to keep secrets protected while in memory so that your app might claim a high
1841 level of security, in case you care about that.
1843 There are some memory protection strategies that B<File::KDBX> does NOT use today but could in the future:
1845 Many systems allow programs to mark unswappable pages. Secret information should ideally be stored in such
1846 pages. You could potentially use L<mlockall(2)> (or equivalent for your system) in your own application to
1847 prevent the entire address space from being swapped.
1849 Some systems provide special syscalls for storing secrets in memory while keeping the encryption key outside
1850 of the program's address space, like C<CryptProtectMemory> for Windows. This could be a good option, though
1851 unfortunately not portable.
1855 Several methods take a I<query> as an argument (e.g. L</find_entries>). A query is just a subroutine that you
1856 can either write yourself or have generated for you based on either a simple expression or a declarative
1857 structure. It's easier to have your query generated, so I'll cover that first.
1859 =head2 Simple Expression
1861 A simple expression is mostly compatible with the KeePass 2 implementation
1862 L<described here|https://keepass.info/help/base/search.html#mode_se>.
1864 An expression is a string with one or more space-separated terms. Terms with spaces can be enclosed in double
1865 quotes. Terms are negated if they are prefixed with a minus sign. A record must match every term on at least
1866 one of the given fields.
1868 So a simple expression is something like what you might type into a search engine. You can generate a simple
1869 expression query using L<File::KDBX::Util/simple_expression_query> or by passing the simple expression as
1870 a B<string reference> to search methods like L</find_entries>.
1872 To search for all entries in a database with the word "canyon" appearing anywhere in the title:
1874 my @entries = $kdbx->find_entries([ \'canyon', qw(title) ]);
1876 Notice the first argument is a B<stringref>. This diambiguates a simple expression from other types of queries
1879 As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that
1880 has the words "red" B<and> "canyon" anywhere in the title:
1882 my @entries = $kdbx->find_entries([ \'red canyon', qw(title) ]);
1884 Each term in the simple expression must be found for an entry to match.
1886 To search for entries with "red" in the title but B<not> "canyon", just prepend "canyon" with a minus sign:
1888 my @entries = $kdbx->find_entries([ \'red -canyon', qw(title) ]);
1890 To search over multiple fields simultaneously, just list them. To search for entries with "grocery" in the
1891 title or notes but not "Foodland":
1893 my @entries = $kdbx->find_entries([ \'grocery -Foodland', qw(title notes) ]);
1895 The default operator is a case-insensitive regexp match, which is fine for searching text loosely. You can use
1896 just about any binary comparison operator that perl supports. To specify an operator, list it after the simple
1897 expression. For example, to search for any entry that has been used at least five times:
1899 my @entries = $kdbx->find_entries([ \5, '>=', qw(usage_count) ]);
1901 It helps to read it right-to-left, like "usage_count is >= 5".
1903 If you find the disambiguating structures to be confusing, you can also the L</find_entries_simple> method as
1904 a more intuitive alternative. The following example is equivalent to the previous:
1906 my @entries = $kdbx->find_entries_simple(5, '>=', qw(usage_count));
1908 =head2 Declarative Query
1910 Structuring a declarative query is similar to L<SQL::Abstract/"WHERE CLAUSES">, but you don't have to be
1911 familiar with that module. Just learn by examples.
1913 To search for all entries in a database titled "My Bank":
1915 my @entries = $kdbx->find_entries({ title => 'My Bank' });
1917 The query here is C<< { title => 'My Bank' } >>. A hashref can contain key-value pairs where the key is
1918 a attribute of the thing being searched for (in this case an entry) and the value is what you want the thing's
1919 attribute to be to consider it a match. In this case, the attribute we're using as our match criteria is
1920 L<File::KDBX::Entry/title>, a text field. If an entry has its title attribute equal to "My Bank", it's
1923 A hashref can contain multiple attributes. The search candidate will be a match if I<all> of the specified
1924 attributes are equal to their respective values. For example, to search for all entries with a particular URL
1927 my @entries = $kdbx->find_entries({
1928 url => 'https://example.com',
1932 To search for entries matching I<any> criteria, just change the hashref to an arrayref. To search for entries
1933 with a particular URL B<OR> a particular username:
1935 my @entries = $kdbx->find_entries([ # <-- square bracket
1936 url => 'https://example.com',
1940 You can user different operators to test different types of attributes. The L<File::KDBX::Entry/icon_id>
1941 attribute is a number, so we should use a number comparison operator. To find entries using the smartphone
1944 my @entries = $kdbx->find_entries({
1945 icon_id => { '==', ICON_SMARTPHONE },
1948 Note: L<File::KDBX::Constants/ICON_SMARTPHONE> is just a constant from L<File::KDBX::Constants>. It isn't
1949 special to this example or to queries generally. We could have just used a literal number.
1951 The important thing to notice here is how we wrapped the condition in another arrayref with a single key-pair
1952 where the key is the name of an operator and the value is the thing to match against. The supported operators
1956 * C<eq> - String equal
1957 * C<ne> - String not equal
1958 * C<lt> - String less than
1959 * C<gt> - String greater than
1960 * C<le> - String less than or equal
1961 * C<ge> - String greater than or equal
1962 * C<==> - Number equal
1963 * C<!=> - Number not equal
1964 * C<< < >> - Number less than
1965 * C<< > >>> - Number greater than
1966 * C<< <= >> - Number less than or equal
1967 * C<< >= >> - Number less than or equal
1968 * C<=~> - String match regular expression
1969 * C<!~> - String does not match regular expression
1970 * C<!> - Boolean false
1971 * C<!!> - Boolean true
1973 Other special operators:
1976 * C<-true> - Boolean true
1977 * C<-false> - Boolean false
1978 * C<-not> - Boolean false (alias for C<-false>)
1979 * C<-defined> - Is defined
1980 * C<-undef> - Is not d efined
1981 * C<-empty> - Is empty
1982 * C<-nonempty> - Is not empty
1983 * C<-or> - Logical or
1984 * C<-and> - Logical and
1986 Let's see another example using an explicit operator. To find all groups except one in particular (identified
1987 by its L<File::KDBX::Group/uuid>), we can use the C<ne> (string not equal) operator:
1989 my ($group, @other) = $kdbx->find_groups({
1991 'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
1994 if (@other) { say "Problem: there can be only one!" }
1996 Note: L<File::KDBX::Util/uuid> is a little helper function to convert a UUID in its pretty form into octets.
1997 This helper function isn't special to this example or to queries generally. It could have been written with
1998 a literal such as C<"\x59\x6f\x75\x20\x61...">, but that's harder to read.
2000 Notice we searched for groups this time. Finding groups works exactly the same as it does for entries.
2002 Testing the truthiness of an attribute is a little bit different because it isn't a binary operation. To find
2003 all entries with the password quality check disabled:
2005 my @entries = $kdbx->find_entries({ '!' => 'quality_check' });
2007 This time the string after the operator is the attribute name rather than a value to compare the attribute
2008 against. To test that a boolean value is true, use the C<!!> operator (or C<-true> if C<!!> seems a little too
2009 weird for your taste):
2011 my @entries = $kdbx->find_entries({ '!!' => 'quality_check' });
2012 my @entries = $kdbx->find_entries({ -true => 'quality_check' });
2014 Yes, there is also a C<-false> and a C<-not> if you prefer one of those over C<!>. C<-false> and C<-not>
2015 (along with C<-true>) are also special in that you can use them to invert the logic of a subquery. These are
2016 logically equivalent:
2018 my @entries = $kdbx->find_entries([ -not => { title => 'My Bank' } ]);
2019 my @entries = $kdbx->find_entries({ title => { 'ne' => 'My Bank' } });
2021 These special operators become more useful when combined with two more special operators: C<-and> and C<-or>.
2022 With these, it is possible to construct more interesting queries with groups of logic. For example:
2024 my @entries = $kdbx->find_entries({
2025 title => { '=~', qr/bank/ },
2028 notes => { '=~', qr/business/ },
2029 icon_id => { '==', ICON_TRASHCAN_FULL },
2034 In English, find entries where the word "bank" appears anywhere in the title but also do not have either the
2035 word "business" in the notes or is using the full trashcan icon.
2037 =head2 Subroutine Query
2039 Lastly, as mentioned at the top, you can ignore all this and write your own subroutine. Your subroutine will
2040 be called once for each thing being searched over. The single argument is the search candidate. The subroutine
2041 should match the candidate against whatever criteria you want and return true if it matches. The C<find_*>
2042 methods collect all matching things and return them.
2044 For example, to find all entries in the database titled "My Bank":
2046 my @entries = $kdbx->find_entries(sub { shift->title eq 'My Bank' });
2047 # logically the same as this declarative structure:
2048 my @entries = $kdbx->find_entries({ title => 'My Bank' });
2049 # as well as this simple expression:
2050 my @entries = $kdbx->find_entries([ \'My Bank', 'eq', qw{title} ]);
2052 This is a trivial example, but of course your subroutine can be arbitrarily complex.
2054 All of these query mechanisms described in this section are just tools, each with its own set of limitations.
2055 If the tools are getting in your way, you can of course iterate over the contents of a database and implement
2056 your own query logic, like this:
2058 for my $entry (@{ $kdbx->all_entries }) {
2059 if (wanted($entry)) {
2060 do_something($entry);
2069 Errors in this package are constructed as L<File::KDBX::Error> objects and propagated using perl's built-in
2070 mechanisms. Fatal errors are propagated using L<functions/die> and non-fatal errors (a.k.a. warnings) are
2071 propagated using L<functions/warn> while adhering to perl's L<warnings> system. If you're already familiar
2072 with these mechanisms, you can skip this section.
2074 You can catch fatal errors using L<functions/eval> (or something like L<Try::Tiny>) and non-fatal errors using
2075 C<$SIG{__WARN__}> (see L<variables/%SIG>). Examples:
2077 use File::KDBX::Error qw(error);
2079 my $key = ''; # uh oh
2081 $kdbx->load_file('whatever.kdbx', $key);
2083 if (my $error = error($@)) {
2084 handle_missing_key($error) if $error->type eq 'key.missing';
2088 or using C<Try::Tiny>:
2091 $kdbx->load_file('whatever.kdbx', $key);
2097 Catching non-fatal errors:
2100 local $SIG{__WARN__} = sub { push @warnings, $_[0] };
2102 $kdbx->load_file('whatever.kdbx', $key);
2104 handle_warnings(@warnings) if @warnings;
2106 By default perl prints warnings to C<STDERR> if you don't catch them. If you don't want to catch them and also
2107 don't want them printed to C<STDERR>, you can suppress them lexically (perl v5.28 or higher required):
2110 no warnings 'File::KDBX';
2117 local $File::KDBX::WARNINGS = 0;
2121 or globally in your program:
2123 $File::KDBX::WARNINGS = 0;
2125 You cannot suppress fatal errors, and if you don't catch them your program will exit.
2129 This software will alter its behavior depending on the value of certain environment variables:
2132 * C<PERL_FILE_KDBX_XS> - Do not use L<File::KDBX::XS> if false (default: true)
2133 * C<PERL_ONLY> - Do not use L<File::KDBX::XS> if true (default: false)
2134 * C<NO_FORK> - Do not fork if true (default: false)
2138 Some features (e.g. parsing) require 64-bit perl. It should be possible and actually pretty easy to make it
2139 work using L<Math::BigInt>, but I need to build a 32-bit perl in order to test it and frankly I'm still
2140 figuring out how. I'm sure it's simple so I'll mark this one "TODO", but for now an exception will be thrown
2141 when trying to use such features with undersized IVs.
2145 L<File::KeePass> is a much older alternative. It's good but has a backlog of bugs and lacks support for newer