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 List
::Util
qw(any);
14 use Ref
::Util
qw(is_ref is_arrayref is_plain_hashref);
15 use Scalar
::Util
qw(blessed refaddr);
18 use warnings
::register
;
21 our $VERSION = '999.999'; # VERSION
29 $kdbx = File
::KDBX-
>new(%attributes);
30 $kdbx = File
::KDBX-
>new($kdbx); # copy constructor
32 Construct a new L
<File
::KDBX
>.
40 return $_[0]->clone if @_ == 1 && blessed
$_[0] && $_[0]->isa($class);
42 my $self = bless {}, $class;
44 $self->_set_default_attributes if empty
$self;
48 sub DESTROY
{ !in_global_destruction
and $_[0]->reset }
52 $kdbx = $kdbx->init(%attributes);
54 Initialize a L
<File
::KDBX
> with a new set of attributes
. Returns itself to allow
method chaining
.
56 This
is called by L
</new
>.
64 @$self{keys %args} = values %args;
73 Set a L
<File
::KDBX
> to an empty
state, ready to load a KDBX file
or build a new one
. Returns itself to allow
80 erase
$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY
};
81 erase
$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY
};
84 delete $SAFE{refaddr
($self)};
91 $kdbx_copy = $kdbx->clone;
92 $kdbx_copy = File
::KDBX-
>new($kdbx);
94 Clone a L
<File
::KDBX
>. The clone will be an exact copy
and completely independent of the original
.
101 return Storable
::dclone
($self);
104 sub STORABLE_freeze
{
110 return '', $copy, $KEYS{refaddr
($self)} // (), $SAFE{refaddr
($self)} // ();
121 @$self{keys %$clone} = values %$clone;
122 $KEYS{refaddr
($self)} = $key;
123 $SAFE{refaddr
($self)} = $safe;
125 for my $object (@{$self->all_groups}, @{$self->all_entries(history
=> 1)}) {
126 $object->kdbx($self);
130 ##############################################################################
140 $kdbx = KDBX
::File-
>load(\
$string, $key);
141 $kdbx = KDBX
::File-
>load(*IO
, $key);
142 $kdbx = KDBX
::File-
>load($filepath, $key);
143 $kdbx->load(...); # also instance method
145 $kdbx = File
::KDBX-
>load_string($string, $key);
146 $kdbx = File
::KDBX-
>load_string(\
$string, $key);
147 $kdbx->load_string(...); # also instance method
149 $kdbx = File
::KDBX-
>load_file($filepath, $key);
150 $kdbx->load_file(...); # also instance method
152 $kdbx = File
::KDBX-
>load_handle($fh, $key);
153 $kdbx = File
::KDBX-
>load_handle(*IO
, $key);
154 $kdbx->load_handle(...); # also instance method
156 Load a KDBX file from a string buffer
, IO handle
or file from a filesystem
.
158 L
<File
::KDBX
::Loader
> does the heavy lifting
.
162 sub load
{ shift-
>_loader->load(@_) }
163 sub load_string
{ shift-
>_loader->load_string(@_) }
164 sub load_file
{ shift-
>_loader->load_file(@_) }
165 sub load_handle
{ shift-
>_loader->load_handle(@_) }
169 $self = $self->new if !ref $self;
170 require File
::KDBX
::Loader
;
171 File
::KDBX
::Loader-
>new(kdbx
=> $self);
182 $kdbx->dump(\
$string, $key);
183 $kdbx->dump(*IO
, $key);
184 $kdbx->dump($filepath, $key);
186 $kdbx->dump_string(\
$string, $key);
187 \
$string = $kdbx->dump_string($key);
189 $kdbx->dump_file($filepath, $key);
191 $kdbx->dump_handle($fh, $key);
192 $kdbx->dump_handle(*IO
, $key);
194 Dump a KDBX file to a string buffer
, IO handle
or file
in a filesystem
.
196 L
<File
::KDBX
::Dumper
> does the heavy lifting
.
200 sub dump { shift-
>_dumper->dump(@_) }
201 sub dump_string
{ shift-
>_dumper->dump_string(@_) }
202 sub dump_file
{ shift-
>_dumper->dump_file(@_) }
203 sub dump_handle
{ shift-
>_dumper->dump_handle(@_) }
207 $self = $self->new if !ref $self;
208 require File
::KDBX
::Dumper
;
209 File
::KDBX
::Dumper-
>new(kdbx
=> $self);
212 ##############################################################################
214 =method user_agent_string
216 $string = $kdbx->user_agent_string;
218 Get a text string identifying the database client software
.
222 sub user_agent_string
{
224 sprintf('%s/%s (%s/%s; %s/%s; %s)',
225 __PACKAGE__
, $VERSION, @Config::Config
{qw(package version osname osvers archname)});
242 =attr deleted_objects
246 $value = $kdbx->$attr;
247 $kdbx->$attr($value);
249 Get
and set attributes
.
256 version
=> KDBX_VERSION_3_1
,
257 headers
=> sub { +{} },
258 inner_headers
=> sub { +{} },
260 binaries
=> sub { +{} },
261 deleted_objects
=> sub { +{} },
264 my %ATTRS_HEADERS = (
265 HEADER_COMMENT
() => '',
266 HEADER_CIPHER_ID
() => CIPHER_UUID_CHACHA20
,
267 HEADER_COMPRESSION_FLAGS
() => COMPRESSION_GZIP
,
268 HEADER_MASTER_SEED
() => sub { random_bytes
(32) },
269 # HEADER_TRANSFORM_SEED() => sub { random_bytes(32) },
270 # HEADER_TRANSFORM_ROUNDS() => 100_000,
271 HEADER_ENCRYPTION_IV
() => sub { random_bytes
(16) },
272 # HEADER_INNER_RANDOM_STREAM_KEY() => sub { random_bytes(32) }, # 64?
273 HEADER_STREAM_START_BYTES
() => sub { random_bytes
(32) },
274 # HEADER_INNER_RANDOM_STREAM_ID() => STREAM_ID_CHACHA20,
275 HEADER_KDF_PARAMETERS
() => sub {
277 KDF_PARAM_UUID
() => KDF_UUID_AES
,
278 KDF_PARAM_AES_ROUNDS
() => $_[0]->headers->{+HEADER_TRANSFORM_ROUNDS
} // KDF_DEFAULT_AES_ROUNDS
,
279 KDF_PARAM_AES_SEED
() => $_[0]->headers->{+HEADER_TRANSFORM_SEED
} // random_bytes
(32),
282 # HEADER_PUBLIC_CUSTOM_DATA() => sub { +{} },
288 database_name_changed
=> sub { gmtime },
289 database_description
=> '',
290 database_description_changed
=> sub { gmtime },
291 default_username
=> '',
292 default_username_changed
=> sub { gmtime },
293 maintenance_history_days
=> 0,
295 master_key_changed
=> sub { gmtime },
296 master_key_change_rec
=> -1,
297 master_key_change_force
=> -1,
298 # memory_protection => sub { +{} },
299 custom_icons
=> sub { +{} },
300 recycle_bin_enabled
=> true
,
301 recycle_bin_uuid
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
302 recycle_bin_changed
=> sub { gmtime },
303 entry_templates_group
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
304 entry_templates_group_changed
=> sub { gmtime },
305 last_selected_group
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
306 last_top_visible_group
=> "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0",
307 history_max_items
=> HISTORY_DEFAULT_MAX_ITEMS
,
308 history_max_size
=> HISTORY_DEFAULT_MAX_SIZE
,
309 settings_changed
=> sub { gmtime },
310 # binaries => sub { +{} },
311 # custom_data => sub { +{} },
313 my %ATTRS_MEMORY_PROTECTION = (
314 protect_title
=> false
,
315 protect_username
=> false
,
316 protect_password
=> true
,
317 protect_url
=> false
,
318 protect_notes
=> false
,
319 auto_enable_visual_hiding
=> false
,
322 sub _update_group_uuid
{
324 my $old_uuid = shift // return;
325 my $new_uuid = shift;
327 my $meta = $self->meta;
328 $self->recycle_bin_uuid($new_uuid) if $old_uuid eq ($meta->{recycle_bin_uuid
} // '');
329 $self->entry_templates_group($new_uuid) if $old_uuid eq ($meta->{entry_templates_group
} // '');
330 $self->last_selected_group($new_uuid) if $old_uuid eq ($meta->{last_selected_group
} // '');
331 $self->last_top_visible_group($new_uuid) if $old_uuid eq ($meta->{last_top_visible_group
} // '');
333 for my $group (@{$self->all_groups}) {
334 $group->last_top_visible_entry($new_uuid) if $old_uuid eq ($group->{last_top_visible_entry
} // '');
335 $group->previous_parent_group($new_uuid) if $old_uuid eq ($group->{previous_parent_group
} // '');
337 for my $entry (@{$self->all_entries}) {
338 $entry->previous_parent_group($new_uuid) if $old_uuid eq ($entry->{previous_parent_group
} // '');
342 sub _update_entry_uuid
{
344 my $old_uuid = shift // return;
345 my $new_uuid = shift;
347 for my $entry (@{$self->all_entries}) {
348 $entry->previous_parent_group($new_uuid) if $old_uuid eq ($entry->{previous_parent_group
} // '');
352 while (my ($attr, $default) = each %ATTRS) {
353 no strict
'refs'; ## no critic (ProhibitNoStrict)
356 $self->{$attr} = shift if @_;
357 $self->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
360 while (my ($attr, $default) = each %ATTRS_HEADERS) {
361 no strict
'refs'; ## no critic (ProhibitNoStrict)
364 $self->headers->{$attr} = shift if @_;
365 $self->headers->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
368 while (my ($attr, $default) = each %ATTRS_META) {
369 no strict
'refs'; ## no critic (ProhibitNoStrict)
372 $self->meta->{$attr} = shift if @_;
373 $self->meta->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
376 while (my ($attr, $default) = each %ATTRS_MEMORY_PROTECTION) {
377 no strict
'refs'; ## no critic (ProhibitNoStrict)
380 $self->meta->{$attr} = shift if @_;
381 $self->meta->{$attr} //= (ref $default eq 'CODE') ? $default->($self) : $default;
386 HEADER_TRANSFORM_SEED
,
387 HEADER_TRANSFORM_ROUNDS
,
388 HEADER_INNER_RANDOM_STREAM_KEY
,
389 HEADER_INNER_RANDOM_STREAM_ID
,
391 sub _set_default_attributes
{
393 $self->$_ for keys %ATTRS, keys %ATTRS_HEADERS, keys %ATTRS_META, keys %ATTRS_MEMORY_PROTECTION,
397 =method memory_protection
399 \
%settings = $kdbx->memory_protection
400 $kdbx->memory_protection(\
%settings);
402 $bool = $kdbx->memory_protection($string_key);
403 $kdbx->memory_protection($string_key => $bool);
405 Get
or set memory protection settings
. This globally
(for the whole database
) configures whether
and which of
406 the standard strings should be memory-protected
. The
default setting
is to memory-protect only I
<Password
>
409 Memory protection can be toggled individually
for each entry string
, and individual settings
take precedence
410 over these global settings
.
414 sub memory_protection
{
416 $self->{meta
}{memory_protection
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
417 return $self->{meta
}{memory_protection
} //= {} if !@_;
419 my $string_key = shift;
420 my $key = 'protect_' . lc($string_key);
422 $self->meta->{memory_protection
}{$key} = shift if @_;
423 $self->meta->{memory_protection
}{$key};
426 =method minimum_version
428 $version = $kdbx->minimum_version;
430 Determine the minimum file version required to save a database losslessly
. Using certain databases features
431 might increase this value
. For example
, setting the KDF to Argon2 will increase the minimum version to at
432 least C
<KDBX_VERSION_4_0
> (i
.e
. C
<0x00040000>) because Argon2 was introduced with KDBX4
.
434 This
method never returns less than C
<KDBX_VERSION_3_1
> (i
.e
. C
<0x00030001>). That file version
is so
435 ubiquitious
and well-supported
, there are seldom reasons to
dump in a lesser format nowadays
.
437 B
<WARNING
:> If you
dump a database with a minimum version higher than the current L
</version
>, the dumper will
438 typically issue a warning
and automatically upgrade the database
. This seems like the safest behavior
in order
439 to avoid data loss
, but lower versions have the benefit of being compatible with more software
. It
is possible
440 to prevent auto-upgrades by explicitly telling the dumper which version to
use, but you
do run the risk of
441 data loss
. A database will never be automatically downgraded
.
445 sub minimum_version
{
448 return KDBX_VERSION_4_1
if any
{
449 nonempty
$_->{last_modification_time
}
450 } values %{$self->custom_data};
452 return KDBX_VERSION_4_1
if any
{
453 nonempty
$_->{name
} || nonempty
$_->{last_modification_time
}
454 } values %{$self->custom_icons};
456 return KDBX_VERSION_4_1
if any
{
457 nonempty
$_->previous_parent_group || nonempty
$_->tags ||
458 any
{ nonempty
$_->{last_modification_time
} } values %{$_->custom_data}
459 } @{$self->all_groups};
461 return KDBX_VERSION_4_1
if any
{
462 nonempty
$_->previous_parent_group || (defined $_->quality_check && !$_->quality_check) ||
463 any
{ nonempty
$_->{last_modification_time
} } values %{$_->custom_data}
464 } @{$self->all_entries(history
=> 1)};
466 return KDBX_VERSION_4_0
if $self->kdf->uuid ne KDF_UUID_AES
;
468 return KDBX_VERSION_4_0
if nonempty
$self->public_custom_data;
470 return KDBX_VERSION_4_0
if any
{
471 nonempty
$_->custom_data
472 } @{$self->all_groups}, @{$self->all_entries(history
=> 1)};
474 return KDBX_VERSION_3_1
;
477 ##############################################################################
481 $kdbx->add_group($group, %options);
482 $kdbx->add_group(%group_attributes, %options);
484 Add a group to a database
. This
is equivalent to identifying a parent group
and calling
485 L
<File
::KDBX
::Group
/add_group
> on the parent group
, forwarding the arguments
. Available options
:
488 * C<group> (aka C<parent>) - Group (object or group UUID) to add the group to (default: root group)
494 my $group = @_ % 2 == 1 ? shift : undef;
497 # find the right group to add the group to
498 my $parent = delete $args{group
} // delete $args{parent
} // $self->root;
499 ($parent) = $self->find_groups({uuid
=> $parent}) if !ref $parent;
500 $parent or throw
'Invalid group';
502 return $parent->add_group(defined $group ? $group : (), %args, kdbx
=> $self);
508 require File
::KDBX
::Group
;
509 return File
::KDBX
::Group-
>wrap($group, $self);
514 $group = $kdbx->root;
517 Get
or set a database
's root group. You don't necessarily need to explicitly create
or set a root group
518 because it autovivifies
when adding entries
and groups to the database
.
520 Every database
has only a single root group at a
time. Some old KDB files might have multiple root groups
.
521 When reading such files
, a single implicit root group
is created to contain the other explicit groups
. When
522 writing to such a format
, if the root group looks like it was implicitly created then it won
't be written and
523 the resulting file might have multiple root groups. This allows working with older files without changing
524 their written internal structure while still adhering to the modern restrictions while the database is opened.
526 B<WARNING:> The root group of a KDBX database contains all of the database's entries
and other groups
. If you
527 replace the root group
, you are essentially replacing the entire database contents with something
else.
534 $self->{root
} = $self->_wrap_group(@_);
535 $self->{root
}->kdbx($self);
537 $self->{root
} //= $self->_implicit_root;
538 return $self->_wrap_group($self->{root
});
543 return [] if !$self->{root
};
544 return $self->_has_implicit_root ? $self->root->groups : [$self->root];
547 sub _has_implicit_root
{
549 my $root = $self->root;
550 my $temp = __PACKAGE__-
>_implicit_root;
551 # If an implicit root group has been changed in any significant way, it is no longer implicit.
552 return $root->name eq $temp->name &&
553 $root->is_expanded ^ $temp->is_expanded &&
554 $root->notes eq $temp->notes &&
555 !@{$root->entries} &&
556 !defined $root->custom_icon_uuid &&
557 !keys %{$root->custom_data} &&
558 $root->icon_id == $temp->icon_id &&
559 $root->expires ^ $temp->expires &&
560 $root->default_auto_type_sequence eq $temp->default_auto_type_sequence &&
561 !defined $root->enable_auto_type &&
562 !defined $root->enable_searching;
567 require File
::KDBX
::Group
;
568 return File
::KDBX
::Group-
>new(
571 notes
=> 'Added as an implicit root group by '.__PACKAGE__
.'.',
572 ref $self ? (kdbx
=> $self) : (),
578 \
@groups = $kdbx->all_groups(%options);
579 \
@groups = $kdbx->all_groups($base_group, %options);
581 Get all groups deeply
in a database
, or all groups within a specified base group
, in a flat array
. Supported
585 * C<base> - Only include groups within a base group (same as C<$base_group>) (default: root)
586 * C<include_base> - Include the base group in the results (default: true)
592 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
593 my $base = $args{base
} // $self->root;
595 my @groups = $args{include_base
} // 1 ? $self->_wrap_group($base) : ();
597 for my $subgroup (@{$base->{groups
} || []}) {
598 my $more = $self->all_groups($subgroup);
599 push @groups, @$more;
605 =method trace_lineage
607 \
@lineage = $kdbx->trace_lineage($group);
608 \
@lineage = $kdbx->trace_lineage($group, $base_group);
609 \
@lineage = $kdbx->trace_lineage($entry);
610 \
@lineage = $kdbx->trace_lineage($entry, $base_group);
612 Get the direct line of ancestors from C
<$base_group> (default: the root group
) to a group
or entry
. The
613 lineage includes the base group but I
<not> the target group
or entry
. Returns C
<undef> if the target
is not in
614 the database structure
.
621 return $object->lineage(@_);
629 push @lineage, $self->root if !@lineage;
630 my $base = $lineage[-1] or return [];
632 my $uuid = $object->uuid;
633 return \
@lineage if any
{ $_->uuid eq $uuid } @{$base->groups || []}, @{$base->entries || []};
635 for my $subgroup (@{$base->groups || []}) {
636 my $result = $self->_trace_lineage($object, @lineage, $subgroup);
637 return $result if $result;
643 @groups = $kdbx->find_groups($query, %options);
645 Find all groups deeply that match to a query
. Options are the same as
for L
</all_groups
>.
647 See L
</QUERY
> for a description of what C
<$query> can be
.
653 my $query = shift or throw
'Must provide a query';
657 include_base
=> $args{include_base
},
659 return @{search
($self->all_groups(%all_groups), is_arrayref
($query) ? @$query : $query)};
667 ##############################################################################
671 $kdbx->add_entry($entry, %options);
672 $kdbx->add_entry(%entry_attributes, %options);
674 Add a entry to a database
. This
is equivalent to identifying a parent group
and calling
675 L
<File
::KDBX
::Group
/add_entry
> on the parent group
, forwarding the arguments
. Available options
:
678 * C<group> (aka C<parent>) - Group (object or group UUID) to add the entry to (default: root group)
684 my $entry = @_ % 2 == 1 ? shift : undef;
687 # find the right group to add the entry to
688 my $parent = delete $args{group
} // delete $args{parent
} // $self->root;
689 ($parent) = $self->find_groups({uuid
=> $parent}) if !ref $parent;
690 $parent or throw
'Invalid group';
692 return $parent->add_entry(defined $entry ? $entry : (), %args, kdbx
=> $self);
698 require File
::KDBX
::Entry
;
699 return File
::KDBX
::Entry-
>wrap($entry, $self);
704 \
@entries = $kdbx->all_entries(%options);
705 \
@entries = $kdbx->all_entries($base_group, %options);
707 Get entries deeply
in a database
, in a flat array
. Supported options
:
710 * C<base> - Only include entries within a base group (same as C<$base_group>) (default: root)
711 * C<auto_type> - Only include entries with auto-type enabled (default: false, include all)
712 * C<search> - Only include entries within groups with search enabled (default: false, include all)
713 * C<history> - Also include historical entries (default: false, include only active entries)
719 my %args = @_ % 2 == 0 ? @_ : (base
=> shift, @_);
721 my $base = $args{base
} // $self->root;
722 my $history = $args{history
};
723 my $search = $args{search
};
724 my $auto_type = $args{auto_type
};
726 my $enable_auto_type = $base->{enable_auto_type
} // true
;
727 my $enable_searching = $base->{enable_searching
} // true
;
730 if ((!$search || $enable_searching) && (!$auto_type || $enable_auto_type)) {
732 map { $self->_wrap_entry($_) }
733 grep { !$auto_type || $_->{auto_type
}{enabled
} }
734 map { $_, $history ? @{$_->{history
} || []} : () }
735 @{$base->{entries
} || []};
738 for my $subgroup (@{$base->{groups
} || []}) {
739 my $more = $self->all_entries($subgroup,
740 auto_type
=> $auto_type,
744 push @entries, @$more;
752 =method find_entries_simple
754 @entries = $kdbx->find_entries($query, %options);
756 @entries = $kdbx->find_entries_simple($expression, \
@fields, %options);
757 @entries = $kdbx->find_entries_simple($expression, $operator, \
@fields, %options);
759 Find all entries deeply that match a query
. Options are the same as
for L
</all_entries
>.
761 See L
</QUERY
> for a description of what C
<$query> can be
.
767 my $query = shift or throw
'Must provide a query';
771 auto_type
=> $args{auto_type
},
772 search
=> $args{search
},
773 history
=> $args{history
},
775 return @{search
($self->all_entries(%all_entries), is_arrayref
($query) ? @$query : $query)};
778 sub find_entries_simple
{
781 my $op = @_ && !is_ref
($_[0]) ? shift : undef;
783 is_arrayref
($fields) or throw
q{Usage: find_entries_simple($expression, [$op,] \@fields)};
784 return $self->find_entries([\
$text, $op, $fields], @_);
787 ##############################################################################
791 \
%icon = $kdbx->custom_icon($uuid);
792 $kdbx->custom_icon($uuid => \
%icon);
793 $kdbx->custom_icon(%icon);
794 $kdbx->custom_icon(uuid
=> $value, %icon);
801 my %args = @_ == 2 ? (uuid
=> shift, value
=> shift)
802 : @_ % 2 == 1 ? (uuid
=> shift, @_) : @_;
804 if (!$args{key
} && !$args{value
}) {
805 my %standard = (key
=> 1, value
=> 1, last_modification_time
=> 1);
806 my @other_keys = grep { !$standard{$_} } keys %args;
807 if (@other_keys == 1) {
808 my $key = $args{key
} = $other_keys[0];
809 $args{value
} = delete $args{$key};
813 my $key = $args{key
} or throw
'Must provide a custom_icons key to access';
815 return $self->{meta
}{custom_icons
}{$key} = $args{value
} if is_plain_hashref
($args{value
});
817 while (my ($field, $value) = each %args) {
818 $self->{meta
}{custom_icons
}{$key}{$field} = $value;
820 return $self->{meta
}{custom_icons
}{$key};
823 =method custom_icon_data
825 $image_data = $kdbx->custom_icon_data($uuid);
831 sub custom_icon_data
{
833 my $uuid = shift // return;
834 return if !exists $self->custom_icons->{$uuid};
835 return $self->custom_icons->{$uuid}{data
};
838 =method add_custom_icon
840 $uuid = $kdbx->add_custom_icon($image_data, %attributes);
842 Add a custom icon
and get its UUID
. If
not provided
, a random UUID will be generated
. Possible attributes
:
845 * C<uuid> - Icon UUID
846 * C<name> - Name of the icon (text, KDBX4.1+)
847 * C<last_modification_time> - Just what it says (datetime, KDBX4.1+)
851 sub add_custom_icon
{
853 my $img = shift or throw
'Must provide image data';
856 my $uuid = $args{uuid
} // generate_uuid
(sub { !$self->custom_icons->{$_} });
857 $self->custom_icons->{$uuid} = {
865 =method remove_custom_icon
867 $kdbx->remove_custom_icon($uuid);
869 Remove a custom icon
.
873 sub remove_custom_icon
{
876 delete $self->custom_icons->{$uuid};
879 ##############################################################################
883 \
%all_data = $kdbx->custom_data;
884 $kdbx->custom_data(\
%all_data);
886 \
%data = $kdbx->custom_data($key);
887 $kdbx->custom_data($key => \
%data);
888 $kdbx->custom_data(%data);
889 $kdbx->custom_data(key
=> $value, %data);
891 Get
and set custom data
. Custom data
is metadata associated with a database
.
893 Each data item can have a few attributes associated with it
.
896 * C<key> - A unique text string identifier used to look up the data item (required)
897 * C<value> - A text string value (required)
898 * C<last_modification_time> (optional, KDBX4.1+)
904 $self->{meta
}{custom_data
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
905 return $self->{meta
}{custom_data
} //= {} if !@_;
907 my %args = @_ == 2 ? (key
=> shift, value
=> shift)
908 : @_ % 2 == 1 ? (key
=> shift, @_) : @_;
910 if (!$args{key
} && !$args{value
}) {
911 my %standard = (key
=> 1, value
=> 1, last_modification_time
=> 1);
912 my @other_keys = grep { !$standard{$_} } keys %args;
913 if (@other_keys == 1) {
914 my $key = $args{key
} = $other_keys[0];
915 $args{value
} = delete $args{$key};
919 my $key = $args{key
} or throw
'Must provide a custom_data key to access';
921 return $self->{meta
}{custom_data
}{$key} = $args{value
} if is_plain_hashref
($args{value
});
923 while (my ($field, $value) = each %args) {
924 $self->{meta
}{custom_data
}{$key}{$field} = $value;
926 return $self->{meta
}{custom_data
}{$key};
929 =method custom_data_value
931 $value = $kdbx->custom_data_value($key);
933 Exactly the same as L
</custom_data
> except returns just the custom data
's value rather than a structure of
934 attributes. This is a shortcut for:
936 my $data = $kdbx->custom_data($key);
937 my $value = defined $data ? $data->{value} : undef;
941 sub custom_data_value {
943 my $data = $self->custom_data(@_) // return;
944 return $data->{value};
947 =method public_custom_data
949 \%all_data = $kdbx->public_custom_data;
950 $kdbx->public_custom_data(\%all_data);
952 $value = $kdbx->public_custom_data($key);
953 $kdbx->public_custom_data($key => $value);
955 Get and set public custom data. Public custom data is similar to custom data but different in some important
956 ways. Public custom data:
959 * can store strings, booleans and up to 64-bit integer values (custom data can only store text values)
960 * is NOT encrypted within a KDBX file (hence the "public" part of the name)
961 * is a flat hash/dict of key-value pairs (no other associated fields like modification times)
965 sub public_custom_data {
967 $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA} = shift if @_ == 1 && is_plain_hashref($_[0]);
968 return $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA} //= {} if !@_;
970 my $key = shift or throw 'Must provide a public_custom_data key to access
';
971 $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA}{$key} = shift if @_;
972 return $self->{headers}{+HEADER_PUBLIC_CUSTOM_DATA}{$key};
975 ##############################################################################
982 # my %options = @_; # prefer_old / prefer_new
983 # $other->merge_from($self);
990 # die 'Not implemented
';
993 ##############################################################################
995 =method resolve_reference
997 $string = $kdbx->resolve_reference($reference);
998 $string = $kdbx->resolve_reference($wanted, $search_in, $expression);
1000 Resolve a L<field reference|https://keepass.info/help/base/fieldrefs.html>. A field reference is a kind of
1001 string placeholder. You can use a field reference to refer directly to a standard field within an entry. Field
1002 references are resolved automatically while expanding entry strings (i.e. replacing placeholders), but you can
1003 use this method to resolve on-the-fly references that aren't part of any actual string
in the database
.
1005 If the reference
does not resolve to any field
, C
<undef> is returned
. If the reference resolves to multiple
1006 fields
, only the first one
is returned
(in the same order as L
</all_entries
>). To avoid ambiguity
, you can
1007 refer to a specific entry by its UUID
.
1009 The syntax of a reference
is: C
<< {REF
:<WantedField
>@<SearchIn
>:<Text
>} >>. C
<Text
> is a
1010 L
</"Simple Expression">. C
<WantedField
> and C
<SearchIn
> are both single character codes representing a field
:
1019 * C<O> - Other custom strings
1021 Since C<O> does not represent any specific field, it cannot be used as the C<WantedField>.
1025 To get the value of the I<UserName> string of the first entry with "My Bank" in the title:
1027 my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
1028 # OR the {REF:...} wrapper is optional
1029 my $username = $kdbx->resolve_reference('U@T:"My Bank"');
1030 # OR separate the arguments
1031 my $username = $kdbx->resolve_reference(U => T => '"My Bank"');
1033 Note how the text is a L</"Simple Expression">, so search terms with spaces must be surrounded in double
1036 To get the I<Password> string of a specific entry (identified by its UUID):
1038 my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');
1042 sub resolve_reference
{
1044 my $wanted = shift // return;
1045 my $search_in = shift;
1048 if (!defined $text) {
1049 $wanted =~ s/^\{REF:([^\}]+)\}$/$1/i;
1050 ($wanted, $search_in, $text) = $wanted =~ /^([TUPANI])\@([TUPANIO]):(.*)$/i;
1052 $wanted && $search_in && nonempty
($text) or return;
1055 T
=> 'expanded_title',
1056 U
=> 'expanded_username',
1057 P
=> 'expanded_password',
1058 A
=> 'expanded_url',
1059 N
=> 'expanded_notes',
1061 O
=> 'other_strings',
1063 $wanted = $fields{$wanted} or return;
1064 $search_in = $fields{$search_in} or return;
1066 my $query = simple_expression_query
($text, ($search_in eq 'id' ? 'eq' : '=~'), $search_in);
1068 my ($entry) = $self->find_entries($query);
1071 return $entry->$wanted;
1074 our %PLACEHOLDERS = (
1075 # placeholder => sub { my ($entry, $arg) = @_; ... };
1076 'TITLE' => sub { $_[0]->expanded_title },
1077 'USERNAME' => sub { $_[0]->expanded_username },
1078 'PASSWORD' => sub { $_[0]->expanded_password },
1079 'NOTES' => sub { $_[0]->expanded_notes },
1080 'S:' => sub { $_[0]->string_value($_[1]) },
1081 'URL' => sub { $_[0]->expanded_url },
1082 'URL:RMVSCM' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
1083 'URL:WITHOUTSCHEME' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
1084 'URL:SCM' => sub { (split_url
($_[0]->url))[0] },
1085 'URL:SCHEME' => sub { (split_url
($_[0]->url))[0] }, # non-standard
1086 'URL:HOST' => sub { (split_url
($_[0]->url))[2] },
1087 'URL:PORT' => sub { (split_url
($_[0]->url))[3] },
1088 'URL:PATH' => sub { (split_url
($_[0]->url))[4] },
1089 'URL:QUERY' => sub { (split_url
($_[0]->url))[5] },
1090 'URL:HASH' => sub { (split_url
($_[0]->url))[6] }, # non-standard
1091 'URL:FRAGMENT' => sub { (split_url
($_[0]->url))[6] }, # non-standard
1092 'URL:USERINFO' => sub { (split_url
($_[0]->url))[1] },
1093 'URL:USERNAME' => sub { (split_url
($_[0]->url))[7] },
1094 'URL:PASSWORD' => sub { (split_url
($_[0]->url))[8] },
1095 'UUID' => sub { local $_ = format_uuid
($_[0]->uuid); s/-//g; $_ },
1096 'REF:' => sub { $_[0]->kdbx->resolve_reference($_[1]) },
1097 'INTERNETEXPLORER' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('iexplore') },
1098 'FIREFOX' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('firefox') },
1099 'GOOGLECHROME' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('google-chrome') },
1100 'OPERA' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('opera') },
1101 'SAFARI' => sub { load_optional
('IPC::Cmd'); IPC
::Cmd
::can_run
('safari') },
1102 'APPDIR' => sub { load_optional
('FindBin'); $FindBin::Bin
},
1103 'GROUP' => sub { my $p = $_[0]->parent; $p ? $p->name : undef },
1104 'GROUP_PATH' => sub { $_[0]->path },
1105 'GROUP_NOTES' => sub { my $p = $_[0]->parent; $p ? $p->notes : undef },
1114 'ENV:' => sub { $ENV{$_[1]} },
1115 'ENV_DIRSEP' => sub { load_optional
('File::Spec')->catfile('', '') },
1116 'ENV_PROGRAMFILES_X86' => sub { $ENV{'ProgramFiles(x86)'} || $ENV{'ProgramFiles'} },
1119 'DT_SIMPLE' => sub { localtime-
>strftime('%Y%m%d%H%M%S') },
1120 'DT_YEAR' => sub { localtime-
>strftime('%Y') },
1121 'DT_MONTH' => sub { localtime-
>strftime('%m') },
1122 'DT_DAY' => sub { localtime-
>strftime('%d') },
1123 'DT_HOUR' => sub { localtime-
>strftime('%H') },
1124 'DT_MINUTE' => sub { localtime-
>strftime('%M') },
1125 'DT_SECOND' => sub { localtime-
>strftime('%S') },
1126 'DT_UTC_SIMPLE' => sub { gmtime-
>strftime('%Y%m%d%H%M%S') },
1127 'DT_UTC_YEAR' => sub { gmtime-
>strftime('%Y') },
1128 'DT_UTC_MONTH' => sub { gmtime-
>strftime('%m') },
1129 'DT_UTC_DAY' => sub { gmtime-
>strftime('%d') },
1130 'DT_UTC_HOUR' => sub { gmtime-
>strftime('%H') },
1131 'DT_UTC_MINUTE' => sub { gmtime-
>strftime('%M') },
1132 'DT_UTC_SECOND' => sub { gmtime-
>strftime('%S') },
1139 'HMACOTP' => sub { $_[0]->hmac_otp },
1140 'TIMEOTP' => sub { $_[0]->time_otp },
1141 'C:' => sub { '' }, # comment
1149 ##############################################################################
1155 Encrypt all protected strings
in a database
. The encrypted strings are stored
in a L
<File
::KDBX
::Safe
>
1156 associated with the database
and the actual strings will be replaced with C
<undef> to indicate their protected
1157 state. Returns itself to allow
method chaining
.
1163 $SAFE{refaddr
($self)} = shift if @_;
1164 $SAFE{refaddr
($self)};
1167 sub _remove_safe
{ delete $SAFE{refaddr
($_[0])} }
1172 $self->_safe and return $self;
1176 my $entries = $self->all_entries(history
=> 1);
1177 for my $entry (@$entries) {
1178 push @strings, grep { $_->{protect
} } values %{$entry->{strings
} || {}};
1181 $self->_safe(File
::KDBX
::Safe-
>new(\
@strings));
1190 Decrypt all protected strings
in a database
, replacing C
<undef> placeholders with unprotected
values. Returns
1191 itself to allow
method chaining
.
1198 my $safe = $self->_safe or return;
1199 return $safe->peek($string);
1204 my $safe = $self->_safe or return $self;
1207 $self->_remove_safe;
1212 # sub unlock_scoped {
1214 # return if !$self->is_locked;
1215 # require Scope::Guard;
1216 # my $guard = Scope::Guard->new(sub { $self->lock });
1223 $bool = $kdbx->is_locked;
1225 Get whether
or not a database
's strings are memory-protected. If this is true, then some or all of the
1226 protected strings within the database will be unavailable (literally have C<undef> values) until L</unlock> is
1231 sub is_locked { $_[0]->_safe ? 1 : 0 }
1233 ##############################################################################
1235 =method randomize_seeds
1237 $kdbx->randomize_seeds;
1239 Set various keys, seeds and IVs to random values. These values are used by the cryptographic functions that
1240 secure the database when dumped. The attributes that will be randomized are:
1244 * L</inner_random_stream_key>
1246 * L</stream_start_bytes>
1247 * L</transform_seed>
1249 Randomizing these values has no effect on a loaded database. These are only used when a database is dumped.
1250 You normally do not need to call this method explicitly because the dumper does it explicitly by default.
1254 sub randomize_seeds {
1256 $self->encryption_iv(random_bytes(16));
1257 $self->inner_random_stream_key(random_bytes(64));
1258 $self->master_seed(random_bytes(32));
1259 $self->stream_start_bytes(random_bytes(32));
1260 $self->transform_seed(random_bytes(32));
1263 ##############################################################################
1268 $key = $kdbx->key($key);
1269 $key = $kdbx->key($primitive);
1271 Get or set a L<File::KDBX::Key>. This is the master key (i.e. a password or a key file that can decrypt
1272 a database). See L<File::KDBX::Key/new> for an explanation of what the primitive can be.
1274 You generally don't need to call this directly because you can provide the key directly to the loader
or
1275 dumper
when loading
or saving a KDBX file
.
1281 $KEYS{refaddr
($self)} = File
::KDBX
::Key-
>new(@_) if @_;
1282 $KEYS{refaddr
($self)};
1285 =method composite_key
1287 $key = $kdbx->composite_key($key);
1288 $key = $kdbx->composite_key($primitive);
1290 Construct a L
<File
::KDBX
::Key
::Composite
> from a primitive
. See L
<File
::KDBX
::Key
/new
> for an explanation of
1291 what the primitive can be
. If the primitive
does not represent a composite key
, it will be wrapped
.
1293 You generally don
't need to call this directly. The parser and writer use it to transform a master key into
1294 a raw encryption key.
1300 require File::KDBX::Key::Composite;
1301 return File::KDBX::Key::Composite->new(@_);
1306 $kdf = $kdbx->kdf(%options);
1307 $kdf = $kdbx->kdf(\%parameters, %options);
1309 Get a L<File::KDBX::KDF> (key derivation function).
1314 * C<params> - KDF parameters, same as C<\%parameters> (default: value of L</kdf_parameters>)
1320 my %args = @_ % 2 == 1 ? (params => shift, @_) : @_;
1322 my $params = $args{params};
1323 my $compat = $args{compatible} // 1;
1325 $params //= $self->kdf_parameters;
1326 $params = {%{$params || {}}};
1328 if (empty $params || !defined $params->{+KDF_PARAM_UUID}) {
1329 $params->{+KDF_PARAM_UUID} = KDF_UUID_AES;
1331 if ($params->{+KDF_PARAM_UUID} eq KDF_UUID_AES) {
1332 # AES_CHALLENGE_RESPONSE is equivalent to AES if there are no challenge-response keys, and since
1333 # non-KeePassXC implementations don't support challenge-response
keys anyway
, there
's no problem with
1334 # always using AES_CHALLENGE_RESPONSE for all KDBX4+ databases.
1335 # For compatibility, we should not *write* AES_CHALLENGE_RESPONSE, but the dumper handles that.
1336 if ($self->version >= KDBX_VERSION_4_0) {
1337 $params->{+KDF_PARAM_UUID} = KDF_UUID_AES_CHALLENGE_RESPONSE;
1339 $params->{+KDF_PARAM_AES_SEED} //= $self->transform_seed;
1340 $params->{+KDF_PARAM_AES_ROUNDS} //= $self->transform_rounds;
1343 require File::KDBX::KDF;
1344 return File::KDBX::KDF->new(%$params);
1347 sub transform_seed {
1349 $self->headers->{+HEADER_TRANSFORM_SEED} =
1350 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_SEED} = shift if @_;
1351 $self->headers->{+HEADER_TRANSFORM_SEED} =
1352 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_SEED} //= random_bytes(32);
1355 sub transform_rounds {
1357 $self->headers->{+HEADER_TRANSFORM_ROUNDS} =
1358 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_ROUNDS} = shift if @_;
1359 $self->headers->{+HEADER_TRANSFORM_ROUNDS} =
1360 $self->headers->{+HEADER_KDF_PARAMETERS}{+KDF_PARAM_AES_ROUNDS} //= 100_000;
1365 $cipher = $kdbx->cipher(key => $key);
1366 $cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);
1368 Get a L<File::KDBX::Cipher> capable of encrypting and decrypting the body of a database file.
1370 A key is required. This should be a raw encryption key made up of a fixed number of octets (depending on the
1371 cipher), not a L<File::KDBX::Key> or primitive.
1373 If not passed, the UUID comes from C<< $kdbx->headers->{cipher_id} >> and the encryption IV comes from
1374 C<< $kdbx->headers->{encryption_iv} >>.
1376 You generally don't need to call this directly
. The parser
and writer
use it to decrypt
and encrypt KDBX
1385 $args{uuid
} //= $self->headers->{+HEADER_CIPHER_ID
};
1386 $args{iv
} //= $self->headers->{+HEADER_ENCRYPTION_IV
};
1388 require File
::KDBX
::Cipher
;
1389 return File
::KDBX
::Cipher-
>new(%args);
1392 =method random_stream
1394 $cipher = $kdbx->random_stream;
1395 $cipher = $kdbx->random_stream(id
=> $stream_id, key
=> $key);
1397 Get a L
<File
::KDBX
::Cipher
::Stream
> for decrypting
and encrypting protected
values.
1399 If
not passed
, the ID
and encryption key comes from C
<< $kdbx->headers->{inner_random_stream_id
} >> and
1400 C
<< $kdbx->headers->{inner_random_stream_key
} >> (respectively
) for KDBX3 files
and from
1401 C
<< $kdbx->inner_headers->{inner_random_stream_key
} >> and
1402 C
<< $kdbx->inner_headers->{inner_random_stream_id
} >> (respectively
) for KDBX4 files
.
1404 You generally don
't need to call this directly. The parser and writer use it to scramble protected strings.
1412 $args{stream_id} //= delete $args{id} // $self->inner_random_stream_id;
1413 $args{key} //= $self->inner_random_stream_key;
1415 require File::KDBX::Cipher;
1416 File::KDBX::Cipher->new(%args);
1419 sub inner_random_stream_id {
1421 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID}
1422 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID} = shift if @_;
1423 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_ID}
1424 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_ID} //= do {
1425 my $version = $self->minimum_version;
1426 $version < KDBX_VERSION_4_0 ? STREAM_ID_SALSA20 : STREAM_ID_CHACHA20;
1430 sub inner_random_stream_key {
1433 # These are probably the same SvPV so erasing one will CoW, but erasing the second should do the
1435 erase \$self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY};
1436 erase \$self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY};
1437 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY}
1438 = $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY} = shift;
1440 $self->inner_headers->{+INNER_HEADER_INNER_RANDOM_STREAM_KEY}
1441 //= $self->headers->{+HEADER_INNER_RANDOM_STREAM_KEY} //= random_bytes(64); # 32
1444 #########################################################################################
1447 # - Fixer tool. Can repair inconsistencies, including:
1448 # - Orphaned binaries... not really a thing anymore since we now distribute binaries amongst entries
1449 # - Unused custom icons (OFF, data loss)
1451 # - All data types are valid
1452 # - date times are correct
1454 # - All UUIDs refer to things that exist
1455 # - previous parent group
1457 # - last selected group
1458 # - last visible group
1459 # - Enforce history size limits (ON)
1460 # - Check headers/meta (ON)
1461 # - Duplicate deleted objects (ON)
1462 # - Duplicate window associations (OFF)
1463 # - Only one root group (ON)
1464 # - Header UUIDs match known ciphers/KDFs?
1467 #########################################################################################
1471 A text string associated with the database. Often unset.
1475 The UUID of a cipher used to encrypt the database when stored as a file.
1477 See L</File::KDBX::Cipher>.
1479 =attr compression_flags
1481 Configuration for whether or not and how the database gets compressed. See
1482 L<File::KDBX::Constants/":compression">.
1486 The master seed is a string of 32 random bytes that is used as salt in hashing the master key when loading
1487 and saving the database. If a challenge-response key is used in the master key, the master seed is also the
1490 The master seed I<should> be changed each time the database is saved to file.
1492 =attr transform_seed
1494 The transform seed is a string of 32 random bytes that is used in the key derivation function, either as the
1495 salt or the key (depending on the algorithm).
1497 The transform seed I<should> be changed each time the database is saved to file.
1499 =attr transform_rounds
1501 The number of rounds or iterations used in the key derivation function. Increasing this number makes loading
1502 and saving the database slower by design in order to make dictionary and brute force attacks more costly.
1506 The initialization vector used by the cipher.
1508 The encryption IV I<should> be changed each time the database is saved to file.
1510 =attr inner_random_stream_key
1512 The encryption key (possibly including the IV, depending on the cipher) used to encrypt the protected strings
1513 within the database.
1515 =attr stream_start_bytes
1517 A string of 32 random bytes written in the header and encrypted in the body. If the bytes do not match when
1518 loading a file then the wrong master key was used or the file is corrupt. Only KDBX 2 and KDBX 3 files use
1519 this. KDBX 4 files use an improved HMAC method to verify the master key and data integrity of the header and
1522 =attr inner_random_stream_id
1524 A number indicating the cipher algorithm used to encrypt the protected strings within the database, usually
1525 Salsa20 or ChaCha20. See L<File::KDBX::Constants/":random_stream">.
1527 =attr kdf_parameters
1529 A hash/dict of key-value pairs used to configure the key derivation function. This is the KDBX4+ way to
1530 configure the KDF, superceding L</transform_seed> and L</transform_rounds>.
1534 The name of the software used to generate the KDBX file.
1538 The header hash used to verify that the file header is not corrupt. (KDBX 2 - KDBX 3.1, removed KDBX 4.0)
1542 Name of the database.
1544 =attr database_name_changed
1546 Timestamp indicating when the database name was last changed.
1548 =attr database_description
1550 Description of the database
1552 =attr database_description_changed
1554 Timestamp indicating when the database description was last changed.
1556 =attr default_username
1558 When a new entry is created, the I<UserName> string will be populated with this value.
1560 =attr default_username_changed
1562 Timestamp indicating when the default username was last changed.
1564 =attr maintenance_history_days
1566 TODO... not really sure what this is. 😀
1570 A color associated with the database (in the form C<#ffffff> where "f" is a hexidecimal digit). Some agents
1571 use this to help users visually distinguish between different databases.
1573 =attr master_key_changed
1575 Timestamp indicating when the master key was last changed.
1577 =attr master_key_change_rec
1579 Number of days until the agent should prompt to recommend changing the master key.
1581 =attr master_key_change_force
1583 Number of days until the agent should prompt to force changing the master key.
1585 Note: This is purely advisory. It is up to the individual agent software to actually enforce it.
1586 C<File::KDBX> does NOT enforce it.
1588 =attr recycle_bin_enabled
1590 Boolean indicating whether removed groups and entries should go to a recycle bin or be immediately deleted.
1592 =attr recycle_bin_uuid
1594 The UUID of a group used to store thrown-away groups and entries.
1596 =attr recycle_bin_changed
1598 Timestamp indicating when the recycle bin was last changed.
1600 =attr entry_templates_group
1602 The UUID of a group containing template entries used when creating new entries.
1604 =attr entry_templates_group_changed
1606 Timestamp indicating when the entry templates group was last changed.
1608 =attr last_selected_group
1610 The UUID of the previously-selected group.
1612 =attr last_top_visible_group
1614 The UUID of the group visible at the top of the list.
1616 =attr history_max_items
1618 The maximum number of historical entries allowed to be saved for each entry.
1620 =attr history_max_size
1622 The maximum total size (in bytes) that each individual entry's history
is allowed to grow
.
1624 =attr settings_changed
1626 Timestamp indicating
when the database settings were
last updated
.
1630 Alias of the L
</memory_protection
> setting
for the I
<Title
> string
.
1632 =attr protect_username
1634 Alias of the L
</memory_protection
> setting
for the I
<UserName
> string
.
1636 =attr protect_password
1638 Alias of the L
</memory_protection
> setting
for the I
<Password
> string
.
1642 Alias of the L
</memory_protection
> setting
for the I
<URL
> string
.
1646 Alias of the L
</memory_protection
> setting
for the I
<Notes
> string
.
1650 #########################################################################################
1652 sub TO_JSON
{ +{%{$_[0]}} }
1657 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
1663 my $kdbx = File::KDBX->new;
1665 my $group = $kdbx->add_group(
1666 name => 'Passwords',
1669 my $entry = $group->add_entry(
1671 password => 's3cr3t',
1674 $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
1676 $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
1678 for my $entry (@{ $kdbx->all_entries }) {
1679 say 'Entry: ', $entry->title;
1684 B<File::KDBX> provides everything you need to work with a KDBX database. A KDBX database is a hierarchical
1685 object database which is commonly used to store secret information securely. It was developed for the KeePass
1686 password safe. See L</"KDBX Introduction"> for more information about KDBX.
1688 This module lets you query entries, create new entries, delete entries and modify entries. The distribution
1689 also includes various parsers and generators for serializing and persisting databases.
1691 This design of this software was influenced by the L<KeePassXC|https://github.com/keepassxreboot/keepassxc>
1692 implementation of KeePass as well as the L<File::KeePass> module. B<File::KeePass> is an alternative module
1693 that works well in most cases but has a small backlog of bugs and security issues and also does not work with
1694 newer KDBX version 4 files. If you're coming here from the B<File::KeePass> world, you might be interested in
1695 L<File::KeePass::KDBX> that is a drop-in replacement for B<File::KeePass> that uses B<File::KDBX> for storage.
1697 =head2 KDBX Introduction
1699 A KDBX database consists of a hierarchical I<group> of I<entries>. Entries can contain zero or more key-value
1700 pairs of I<strings> and zero or more I<binaries> (i.e. octet strings). Groups, entries, strings and binaries:
1701 that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is associated with each entry, group
1702 and the database as a whole.
1704 You can think of a KDBX database kind of like a file system, where groups are directories, entries are files,
1705 and strings and binaries make up a file's contents.
1707 Databases are typically persisted as a encrypted, compressed files. They are usually accessed directly (i.e.
1708 not over a network). The primary focus of this type of database is data security. It is ideal for storing
1709 relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as
1710 have the correct I<master key>. Even if the database file were to be "leaked" to the public Internet, it
1711 should be virtually impossible to crack with a strong key. See L</SECURITY> for an overview of security
1716 =head2 Create a new database
1718 my $kdbx = File::KDBX->new;
1720 my $group = $kdbx->add_group(name => 'Passwords);
1721 my $entry = $group->add_entry(
1722 title => 'WayneCorp',
1723 username => 'bwayne',
1724 password => 'iambatman',
1725 url => 'https://example.com/login'
1727 $entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');
1729 $kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');
1731 =head2 Read an existing database
1733 my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
1736 for my $entry (@{ $kdbx->all_entries }) {
1737 say 'Found password for ', $entry->title, ':';
1738 say ' Username: ', $entry->username;
1739 say ' Password: ', $entry->password;
1742 =head2 Search for entries
1744 my @entries = $kdbx->find_entries({
1745 title => 'WayneCorp',
1748 See L</QUERY> for many more query examples.
1750 =head2 Search for entries by auto-type window association
1752 my @entry_key_sequences = $kdbx->find_entries_for_window('WayneCorp - Mozilla Firefox');
1753 for my $pair (@entry_key_sequences) {
1754 my ($entry, $key_sequence) = @$pair;
1755 say 'Entry title: ', $entry->title, ', key sequence: ', $key_sequence;
1760 Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}
1764 One of the biggest threats to your database security is how easily the encryption key can be brute-forced.
1765 Strong brute-force protection depends on a couple factors:
1768 * Using unguessable passwords, passphrases and key files.
1769 * Using a brute-force resistent key derivation function.
1771 The first factor is up to you. This module does not enforce strong master keys. It is up to you to pick or
1772 generate strong keys.
1774 The KDBX format allows for the key derivation function to be tuned. The idea is that you want each single
1775 brute-foce attempt to be expensive (in terms of time, CPU usage or memory usage), so that making a lot of
1776 attempts (which would be required if you have a strong master key) gets I<really> expensive.
1778 How expensive you want to make each attempt is up to you and can depend on the application.
1780 This and other KDBX-related security issues are covered here more in depth:
1781 L<https://keepass.info/help/base/security.html>
1783 Here are other security risks you should be thinking about:
1787 This distribution uses the excellent L<CryptX> and L<Crypt::Argon2> packages to handle all crypto-related
1788 functions. As such, a lot of the security depends on the quality of these dependencies. Fortunately these
1789 modules are maintained and appear to have good track records.
1791 The KDBX format has evolved over time to incorporate improved security practices and cryptographic functions.
1792 This package uses the following functions for authentication, hashing, encryption and random number
1798 * Argon2d & Argon2id
1803 * Salsa20 & ChaCha20
1806 At the time of this writing, I am not aware of any successful attacks against any of these functions. These
1807 are among the most-analyzed and widely-adopted crypto functions available.
1809 The KDBX format allows the body cipher and key derivation function to be configured. If a flaw is discovered
1810 in one of these functions, you can hopefully just switch to a better function without needing to update this
1811 software. A later software release may phase out the use of any functions which are no longer secure.
1813 =head2 Memory Protection
1815 It is not a good idea to keep secret information unencrypted in system memory for longer than is needed. The
1816 address space of your program can generally be read by a user with elevated privileges on the system. If your
1817 system is memory-constrained or goes into a hibernation mode, the contents of your address space could be
1818 written to a disk where it might be persisted for long time.
1820 There might be system-level things you can do to reduce your risk, like using swap encryption and limiting
1821 system access to your program's address space while your program is running.
1823 B<File::KDBX> helps minimize (but not eliminate) risk by keeping secrets encrypted in memory until accessed
1824 and zeroing out memory that holds secrets after they're no longer needed, but it's not a silver bullet.
1826 For one thing, the encryption key is stored in the same address space. If core is dumped, the encryption key
1827 is available to be found out. But at least there is the chance that the encryption key and the encrypted
1828 secrets won't both be paged out while memory-constrained.
1830 Another problem is that some perls (somewhat notoriously) copy around memory behind the scenes willy nilly,
1831 and it's difficult know when perl makes a copy of a secret in order to be able to zero it out later. It might
1832 be impossible. The good news is that perls with SvPV copy-on-write (enabled by default beginning with perl
1833 5.20) are much better in this regard. With COW, it's mostly possible to know what operations will cause perl
1834 to copy the memory of a scalar string, and the number of copies will be significantly reduced. There is a unit
1835 test named F<t/memory-protection.t> in this distribution that can be run on POSIX systems to determine how
1836 well B<File::KDBX> memory protection is working.
1838 Memory protection also depends on how your application handles secrets. If your app code is handling scalar
1839 strings with secret information, it's up to you to make sure its memory is zeroed out when no longer needed.
1840 L<File::KDBX::Util/erase> et al. provide some tools to help accomplish this. Or if you're not too concerned
1841 about the risks memory protection is meant to mitigate, then maybe don't worry about it. The security policy
1842 of B<File::KDBX> is to try hard to keep secrets protected while in memory so that your app might claim a high
1843 level of security, in case you care about that.
1845 There are some memory protection strategies that B<File::KDBX> does NOT use today but could in the future:
1847 Many systems allow programs to mark unswappable pages. Secret information should ideally be stored in such
1848 pages. You could potentially use L<mlockall(2)> (or equivalent for your system) in your own application to
1849 prevent the entire address space from being swapped.
1851 Some systems provide special syscalls for storing secrets in memory while keeping the encryption key outside
1852 of the program's address space, like C<CryptProtectMemory> for Windows. This could be a good option, though
1853 unfortunately not portable.
1857 Several methods take a I<query> as an argument (e.g. L</find_entries>). A query is just a subroutine that you
1858 can either write yourself or have generated for you based on either a simple expression or a declarative
1859 structure. It's easier to have your query generated, so I'll cover that first.
1861 =head2 Simple Expression
1863 A simple expression is mostly compatible with the KeePass 2 implementation
1864 L<described here|https://keepass.info/help/base/search.html#mode_se>.
1866 An expression is a string with one or more space-separated terms. Terms with spaces can be enclosed in double
1867 quotes. Terms are negated if they are prefixed with a minus sign. A record must match every term on at least
1868 one of the given fields.
1870 So a simple expression is something like what you might type into a search engine. You can generate a simple
1871 expression query using L<File::KDBX::Util/simple_expression_query> or by passing the simple expression as
1872 a B<string reference> to search methods like L</find_entries>.
1874 To search for all entries in a database with the word "canyon" appearing anywhere in the title:
1876 my @entries = $kdbx->find_entries([ \'canyon', qw(title) ]);
1878 Notice the first argument is a B<stringref>. This diambiguates a simple expression from other types of queries
1881 As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that
1882 has the words "red" B<and> "canyon" anywhere in the title:
1884 my @entries = $kdbx->find_entries([ \'red canyon', qw(title) ]);
1886 Each term in the simple expression must be found for an entry to match.
1888 To search for entries with "red" in the title but B<not> "canyon", just prepend "canyon" with a minus sign:
1890 my @entries = $kdbx->find_entries([ \'red -canyon', qw(title) ]);
1892 To search over multiple fields simultaneously, just list them. To search for entries with "grocery" in the
1893 title or notes but not "Foodland":
1895 my @entries = $kdbx->find_entries([ \'grocery -Foodland', qw(title notes) ]);
1897 The default operator is a case-insensitive regexp match, which is fine for searching text loosely. You can use
1898 just about any binary comparison operator that perl supports. To specify an operator, list it after the simple
1899 expression. For example, to search for any entry that has been used at least five times:
1901 my @entries = $kdbx->find_entries([ \5, '>=', qw(usage_count) ]);
1903 It helps to read it right-to-left, like "usage_count is >= 5".
1905 If you find the disambiguating structures to be confusing, you can also the L</find_entries_simple> method as
1906 a more intuitive alternative. The following example is equivalent to the previous:
1908 my @entries = $kdbx->find_entries_simple(5, '>=', qw(usage_count));
1910 =head2 Declarative Query
1912 Structuring a declarative query is similar to L<SQL::Abstract/"WHERE CLAUSES">, but you don't have to be
1913 familiar with that module. Just learn by examples.
1915 To search for all entries in a database titled "My Bank":
1917 my @entries = $kdbx->find_entries({ title => 'My Bank' });
1919 The query here is C<< { title => 'My Bank' } >>. A hashref can contain key-value pairs where the key is
1920 a attribute of the thing being searched for (in this case an entry) and the value is what you want the thing's
1921 attribute to be to consider it a match. In this case, the attribute we're using as our match criteria is
1922 L<File::KDBX::Entry/title>, a text field. If an entry has its title attribute equal to "My Bank", it's
1925 A hashref can contain multiple attributes. The search candidate will be a match if I<all> of the specified
1926 attributes are equal to their respective values. For example, to search for all entries with a particular URL
1929 my @entries = $kdbx->find_entries({
1930 url => 'https://example.com',
1934 To search for entries matching I<any> criteria, just change the hashref to an arrayref. To search for entries
1935 with a particular URL B<OR> a particular username:
1937 my @entries = $kdbx->find_entries([ # <-- square bracket
1938 url => 'https://example.com',
1942 You can user different operators to test different types of attributes. The L<File::KDBX::Entry/icon_id>
1943 attribute is a number, so we should use a number comparison operator. To find entries using the smartphone
1946 my @entries = $kdbx->find_entries({
1947 icon_id => { '==', ICON_SMARTPHONE },
1950 Note: L<File::KDBX::Constants/ICON_SMARTPHONE> is just a constant from L<File::KDBX::Constants>. It isn't
1951 special to this example or to queries generally. We could have just used a literal number.
1953 The important thing to notice here is how we wrapped the condition in another arrayref with a single key-pair
1954 where the key is the name of an operator and the value is the thing to match against. The supported operators
1958 * C<eq> - String equal
1959 * C<ne> - String not equal
1960 * C<lt> - String less than
1961 * C<gt> - String greater than
1962 * C<le> - String less than or equal
1963 * C<ge> - String greater than or equal
1964 * C<==> - Number equal
1965 * C<!=> - Number not equal
1966 * C<< < >> - Number less than
1967 * C<< > >>> - Number greater than
1968 * C<< <= >> - Number less than or equal
1969 * C<< >= >> - Number less than or equal
1970 * C<=~> - String match regular expression
1971 * C<!~> - String does not match regular expression
1972 * C<!> - Boolean false
1973 * C<!!> - Boolean true
1975 Other special operators:
1978 * C<-true> - Boolean true
1979 * C<-false> - Boolean false
1980 * C<-not> - Boolean false (alias for C<-false>)
1981 * C<-defined> - Is defined
1982 * C<-undef> - Is not d efined
1983 * C<-empty> - Is empty
1984 * C<-nonempty> - Is not empty
1985 * C<-or> - Logical or
1986 * C<-and> - Logical and
1988 Let's see another example using an explicit operator. To find all groups except one in particular (identified
1989 by its L<File::KDBX::Group/uuid>), we can use the C<ne> (string not equal) operator:
1991 my ($group, @other) = $kdbx->find_groups({
1993 'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
1996 if (@other) { say "Problem: there can be only one!" }
1998 Note: L<File::KDBX::Util/uuid> is a little helper function to convert a UUID in its pretty form into octets.
1999 This helper function isn't special to this example or to queries generally. It could have been written with
2000 a literal such as C<"\x59\x6f\x75\x20\x61...">, but that's harder to read.
2002 Notice we searched for groups this time. Finding groups works exactly the same as it does for entries.
2004 Testing the truthiness of an attribute is a little bit different because it isn't a binary operation. To find
2005 all entries with the password quality check disabled:
2007 my @entries = $kdbx->find_entries({ '!' => 'quality_check' });
2009 This time the string after the operator is the attribute name rather than a value to compare the attribute
2010 against. To test that a boolean value is true, use the C<!!> operator (or C<-true> if C<!!> seems a little too
2011 weird for your taste):
2013 my @entries = $kdbx->find_entries({ '!!' => 'quality_check' });
2014 my @entries = $kdbx->find_entries({ -true => 'quality_check' });
2016 Yes, there is also a C<-false> and a C<-not> if you prefer one of those over C<!>. C<-false> and C<-not>
2017 (along with C<-true>) are also special in that you can use them to invert the logic of a subquery. These are
2018 logically equivalent:
2020 my @entries = $kdbx->find_entries([ -not => { title => 'My Bank' } ]);
2021 my @entries = $kdbx->find_entries({ title => { 'ne' => 'My Bank' } });
2023 These special operators become more useful when combined with two more special operators: C<-and> and C<-or>.
2024 With these, it is possible to construct more interesting queries with groups of logic. For example:
2026 my @entries = $kdbx->find_entries({
2027 title => { '=~', qr/bank/ },
2030 notes => { '=~', qr/business/ },
2031 icon_id => { '==', ICON_TRASHCAN_FULL },
2036 In English, find entries where the word "bank" appears anywhere in the title but also do not have either the
2037 word "business" in the notes or is using the full trashcan icon.
2039 =head2 Subroutine Query
2041 Lastly, as mentioned at the top, you can ignore all this and write your own subroutine. Your subroutine will
2042 be called once for each thing being searched over. The single argument is the search candidate. The subroutine
2043 should match the candidate against whatever criteria you want and return true if it matches. The C<find_*>
2044 methods collect all matching things and return them.
2046 For example, to find all entries in the database titled "My Bank":
2048 my @entries = $kdbx->find_entries(sub { shift->title eq 'My Bank' });
2049 # logically the same as this declarative structure:
2050 my @entries = $kdbx->find_entries({ title => 'My Bank' });
2051 # as well as this simple expression:
2052 my @entries = $kdbx->find_entries([ \'My Bank', 'eq', qw{title} ]);
2054 This is a trivial example, but of course your subroutine can be arbitrarily complex.
2056 All of these query mechanisms described in this section are just tools, each with its own set of limitations.
2057 If the tools are getting in your way, you can of course iterate over the contents of a database and implement
2058 your own query logic, like this:
2060 for my $entry (@{ $kdbx->all_entries }) {
2061 if (wanted($entry)) {
2062 do_something($entry);
2071 Errors in this package are constructed as L<File::KDBX::Error> objects and propagated using perl's built-in
2072 mechanisms. Fatal errors are propagated using L<functions/die> and non-fatal errors (a.k.a. warnings) are
2073 propagated using L<functions/warn> while adhering to perl's L<warnings> system. If you're already familiar
2074 with these mechanisms, you can skip this section.
2076 You can catch fatal errors using L<functions/eval> (or something like L<Try::Tiny>) and non-fatal errors using
2077 C<$SIG{__WARN__}> (see L<variables/%SIG>). Examples:
2079 use File::KDBX::Error qw(error);
2081 my $key = ''; # uh oh
2083 $kdbx->load_file('whatever.kdbx', $key);
2085 if (my $error = error($@)) {
2086 handle_missing_key($error) if $error->type eq 'key.missing';
2090 or using C<Try::Tiny>:
2093 $kdbx->load_file('whatever.kdbx', $key);
2099 Catching non-fatal errors:
2102 local $SIG{__WARN__} = sub { push @warnings, $_[0] };
2104 $kdbx->load_file('whatever.kdbx', $key);
2106 handle_warnings(@warnings) if @warnings;
2108 By default perl prints warnings to C<STDERR> if you don't catch them. If you don't want to catch them and also
2109 don't want them printed to C<STDERR>, you can suppress them lexically (perl v5.28 or higher required):
2112 no warnings 'File::KDBX';
2119 local $File::KDBX::WARNINGS = 0;
2123 or globally in your program:
2125 $File::KDBX::WARNINGS = 0;
2127 You cannot suppress fatal errors, and if you don't catch them your program will exit.
2131 This software will alter its behavior depending on the value of certain environment variables:
2134 * C<PERL_FILE_KDBX_XS> - Do not use L<File::KDBX::XS> if false (default: true)
2135 * C<PERL_ONLY> - Do not use L<File::KDBX::XS> if true (default: false)
2136 * C<NO_FORK> - Do not fork if true (default: false)
2140 Some features (e.g. parsing) require 64-bit perl. It should be possible and actually pretty easy to make it
2141 work using L<Math::BigInt>, but I need to build a 32-bit perl in order to test it and frankly I'm still
2142 figuring out how. I'm sure it's simple so I'll mark this one "TODO", but for now an exception will be thrown
2143 when trying to use such features with undersized IVs.
2147 L<File::KeePass> is a much older alternative. It's good but has a backlog of bugs and lacks support for newer