package File::KDBX;
-# ABSTRACT: Encrypted databases to store secret text and files
+# ABSTRACT: Encrypted database to store secret text and files
+use 5.010;
use warnings;
use strict;
+use Crypt::Digest qw(digest_data);
use Crypt::PRNG qw(random_bytes);
use Devel::GlobalDestruction;
use File::KDBX::Constants qw(:all :icon);
use List::Util qw(any first);
use Ref::Util qw(is_ref is_arrayref is_plain_hashref);
use Scalar::Util qw(blessed);
-use Time::Piece;
+use Time::Piece 1.33;
use boolean;
use namespace::clean;
has 'meta.database_description_changed' => sub { gmtime }, coerce => \&to_time;
has 'meta.default_username' => '', coerce => \&to_string;
has 'meta.default_username_changed' => sub { gmtime }, coerce => \&to_time;
-has 'meta.maintenance_history_days' => 0, coerce => \&to_number;
+has 'meta.maintenance_history_days' => HISTORY_DEFAULT_MAX_AGE, coerce => \&to_number;
has 'meta.color' => '', coerce => \&to_string;
has 'meta.master_key_changed' => sub { gmtime }, coerce => \&to_time;
has 'meta.master_key_change_rec' => -1, coerce => \&to_number;
least C<KDBX_VERSION_4_0> (i.e. C<0x00040000>) because Argon2 was introduced with KDBX4.
This method never returns less than C<KDBX_VERSION_3_1> (i.e. C<0x00030001>). That file version is so
-ubiquitious and well-supported, there are seldom reasons to dump in a lesser format nowadays.
+ubiquitous and well-supported, there are seldom reasons to dump in a lesser format nowadays.
B<WARNING:> If you dump a database with a minimum version higher than the current L</version>, the dumper will
typically issue a warning and automatically upgrade the database. This seems like the safest behavior in order
nonempty $_->previous_parent_group ||
nonempty $_->tags ||
(any { nonempty $_->{last_modification_time} } values %{$_->custom_data})
- # TODO replace next paragraph with this
- # || $_->entries(history => 1)->next(sub {
- # nonempty $_->previous_parent_group ||
- # (defined $_->quality_check && !$_->quality_check) ||
- # (any { nonempty $_->{last_modification_time} } values %{$_->custom_data})
- # })
});
return KDBX_VERSION_4_1 if $self->entries(history => 1)->next(sub {
Every database has only a single root group at a time. Some old KDB files might have multiple root groups.
When reading such files, a single implicit root group is created to contain the actual root groups. When
writing to such a format, if the root group looks like it was implicitly created then it won't be written and
-the resulting file might have multiple root groups. This allows working with older files without changing
-their written internal structure while still adhering to modern semantics while the database is opened.
+the resulting file might have multiple root groups, as it was before loading. This allows working with older
+files without changing their written internal structure while still adhering to modern semantics while the
+database is opened.
The root group of a KDBX database contains all of the database's entries and other groups. If you replace the
root group, you are essentially replacing the entire database contents with something else.
L<File::KDBX::Group/add_group> on the parent group, forwarding the arguments. Available options:
=for :list
-* C<group> (aka C<parent>) - Group object or group UUID to add the group to (default: root group)
+* C<group> - Group object or group UUID to add the group to (default: root group)
=cut
my %args = @_;
# find the right group to add the group to
- my $parent = delete $args{group} // delete $args{parent} // $self->root;
+ my $parent = delete $args{group} // $self->root;
$parent = $self->groups->grep({uuid => $parent})->next if !ref $parent;
$parent or throw 'Invalid group';
\&iterator = $kdbx->groups(%options);
\&iterator = $kdbx->groups($base_group, %options);
-Get an iterator over I<groups> within a database. Options:
+Get an L<File::KDBX::Iterator> over I<groups> within a database. Options:
=for :list
* C<base> - Only include groups within a base group (same as C<$base_group>) (default: L</root>)
my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
my $base = delete $args{base} // $self->root;
- return $base->groups_deeply(%args);
+ return $base->all_groups(%args);
}
##############################################################################
L<File::KDBX::Group/add_entry> on the parent group, forwarding the arguments. Available options:
=for :list
-* C<group> (aka C<parent>) - Group object or group UUID to add the entry to (default: root group)
+* C<group> - Group object or group UUID to add the entry to (default: root group)
=cut
my %args = @_;
# find the right group to add the entry to
- my $parent = delete $args{group} // delete $args{parent} // $self->root;
+ my $parent = delete $args{group} // $self->root;
$parent = $self->groups->grep({uuid => $parent})->next if !ref $parent;
$parent or throw 'Invalid group';
\&iterator = $kdbx->entries(%options);
\&iterator = $kdbx->entries($base_group, %options);
-Get an iterator over I<entries> within a database. Supports the same options as L</groups>, plus some new
-ones:
+Get an L<File::KDBX::Iterator> over I<entries> within a database. Supports the same options as L</groups>,
+plus some new ones:
=for :list
* C<auto_type> - Only include entries with auto-type enabled (default: false, include all)
-* C<searching> - Only include entries within groups with search enabled (default: false, include all)
+* C<searching> - Only include entries within groups with searching enabled (default: false, include all)
* C<history> - Also include historical entries (default: false, include only current entries)
=cut
my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
my $base = delete $args{base} // $self->root;
- return $base->entries_deeply(%args);
+ return $base->all_entries(%args);
}
##############################################################################
\&iterator = $kdbx->objects(%options);
\&iterator = $kdbx->objects($base_group, %options);
-Get an iterator over I<objects> within a database. Groups and entries are considered objects, so this is
-essentially a combination of L</groups> and L</entries>. This won't often be useful, but it can be convenient
-for maintenance tasks. This method takes the same options as L</groups> and L</entries>.
+Get an L<File::KDBX::Iterator> over I<objects> within a database. Groups and entries are considered objects,
+so this is essentially a combination of L</groups> and L</entries>. This won't often be useful, but it can be
+convenient for maintenance tasks. This method takes the same options as L</groups> and L</entries>.
=cut
my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
my $base = delete $args{base} // $self->root;
- return $base->objects_deeply(%args);
+ return $base->all_objects(%args);
}
sub __iter__ { $_[0]->objects }
=method add_custom_icon
$uuid = $kdbx->add_custom_icon($image_data, %attributes);
+ $uuid = $kdbx->add_custom_icon(%attributes);
Add a custom icon and get its UUID. If not provided, a random UUID will be generated. Possible attributes:
=for :list
* C<uuid> - Icon UUID (default: autogenerated)
+* C<data> - Image data (same as C<$image_data>)
* C<name> - Name of the icon (text, KDBX4.1+)
* C<last_modification_time> - Just what it says (datetime, KDBX4.1+)
sub add_custom_icon {
my $self = shift;
- my $img = shift or throw 'Must provide image data';
- my %args = @_;
+ my %args = @_ % 2 == 1 ? (data => shift, @_) : @_;
+
+ defined $args{data} or throw 'Must provide image data';
my $uuid = $args{uuid} // generate_uuid;
push @{$self->custom_icons}, {
@_,
uuid => $uuid,
- data => $img,
+ data => $args{data},
};
return $uuid;
}
$wanted && $search_in && nonempty($text) or return;
my %fields = (
- T => 'expanded_title',
- U => 'expanded_username',
- P => 'expanded_password',
- A => 'expanded_url',
- N => 'expanded_notes',
+ T => 'expand_title',
+ U => 'expand_username',
+ P => 'expand_password',
+ A => 'expand_url',
+ N => 'expand_notes',
I => 'uuid',
O => 'other_strings',
);
our %PLACEHOLDERS = (
# 'PLACEHOLDER' => sub { my ($entry, $arg) = @_; ... };
- 'TITLE' => sub { $_[0]->expanded_title },
- 'USERNAME' => sub { $_[0]->expanded_username },
- 'PASSWORD' => sub { $_[0]->expanded_password },
- 'NOTES' => sub { $_[0]->expanded_notes },
+ 'TITLE' => sub { $_[0]->expand_title },
+ 'USERNAME' => sub { $_[0]->expand_username },
+ 'PASSWORD' => sub { $_[0]->expand_password },
+ 'NOTES' => sub { $_[0]->expand_notes },
'S:' => sub { $_[0]->string_value($_[1]) },
- 'URL' => sub { $_[0]->expanded_url },
+ 'URL' => sub { $_[0]->expand_url },
'URL:RMVSCM' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
'URL:WITHOUTSCHEME' => sub { local $_ = $_[0]->url; s!^[^:/\?\#]+://!!; $_ },
'URL:SCM' => sub { (split_url($_[0]->url))[0] },
$kdbx->lock;
-Encrypt all protected binaries strings in a database. The encrypted strings are stored in
-a L<File::KDBX::Safe> associated with the database and the actual strings will be replaced with C<undef> to
+Encrypt all protected strings and binaries in a database. The encrypted data is stored in
+a L<File::KDBX::Safe> associated with the database and the actual values will be replaced with C<undef> to
indicate their protected state. Returns itself to allow method chaining.
+You can call C<lock> on an already-locked database to memory-protect any unprotected strings and binaries
+added after the last time the database was locked.
+
=cut
sub _safe {
$kdbx->unlock;
-Decrypt all protected strings in a database, replacing C<undef> placeholders with unprotected values. Returns
-itself to allow method chaining.
+Decrypt all protected strings and binaries in a database, replacing C<undef> value placeholders with their
+actual, unprotected values. Returns itself to allow method chaining.
=cut
See L</lock> and L</unlock>.
+Example:
+
+ {
+ my $guard = $kdbx->unlock_scoped;
+ ...;
+ }
+ # $kdbx is now memory-locked
+
=cut
sub unlock_scoped {
$bool = $kdbx->is_locked;
-Get whether or not a database's strings are memory-protected. If this is true, then some or all of the
-protected strings within the database will be unavailable (literally have C<undef> values) until L</unlock> is
-called.
+Get whether or not a database's contents are in a locked (i.e. memory-protected) state. If this is true, then
+some or all of the protected strings and binaries within the database will be unavailable (literally have
+C<undef> values) until L</unlock> is called.
=cut
-sub is_locked { $_[0]->_safe ? 1 : 0 }
+sub is_locked { !!$_[0]->_safe }
##############################################################################
+# sub check {
+# - Fixer tool. Can repair inconsistencies, including:
+# - Orphaned binaries... not really a thing anymore since we now distribute binaries amongst entries
+# - Unused custom icons (OFF, data loss)
+# - Duplicate icons
+# - All data types are valid
+# - date times are correct
+# - boolean fields
+# - All UUIDs refer to things that exist
+# - previous parent group
+# - recycle bin
+# - last selected group
+# - last visible group
+# - Enforce history size limits (ON)
+# - Check headers/meta (ON)
+# - Duplicate deleted objects (ON)
+# - Duplicate window associations (OFF)
+# - Header UUIDs match known ciphers/KDFs?
+# }
+
+=method remove_empty_groups
+
+ $kdbx->remove_empty_groups;
+
+Remove groups with no subgroups and no entries.
+
+=cut
+
+sub remove_empty_groups {
+ my $self = shift;
+ my @removed;
+ $self->groups(algorithm => 'dfs')
+ ->where(-true => 'is_empty')
+ ->each(sub { push @removed, $_->remove });
+ return @removed;
+}
+
+=method remove_unused_icons
+
+ $kdbx->remove_unused_icons;
+
+Remove icons that are not associated with any entry or group in the database.
+
+=cut
+
+sub remove_unused_icons {
+ my $self = shift;
+ my %icons = map { $_->{uuid} => 0 } @{$self->custom_icons};
+
+ $self->objects->each(sub { ++$icons{$_->custom_icon_uuid // ''} });
+
+ my @removed;
+ push @removed, $self->remove_custom_icon($_) for grep { $icons{$_} == 0 } keys %icons;
+ return @removed;
+}
+
+=method remove_duplicate_icons
+
+ $kdbx->remove_duplicate_icons;
+
+Remove duplicate icons as determined by hashing the icon data.
+
+=cut
+
+sub remove_duplicate_icons {
+ my $self = shift;
+
+ my %seen;
+ my %dup;
+ for my $icon (@{$self->custom_icons}) {
+ my $digest = digest_data('SHA256', $icon->{data});
+ if (my $other = $seen{$digest}) {
+ $dup{$icon->{uuid}} = $other->{uuid};
+ }
+ else {
+ $seen{$digest} = $icon;
+ }
+ }
+
+ my @removed;
+ while (my ($old_uuid, $new_uuid) = each %dup) {
+ $self->objects
+ ->where(custom_icon_uuid => $old_uuid)
+ ->each(sub { $_->custom_icon_uuid($new_uuid) });
+ push @removed, $self->remove_custom_icon($old_uuid);
+ }
+ return @removed;
+}
+
+=method prune_history
+
+ $kdbx->prune_history(%options);
+
+Remove just as many older historical entries as necessary to get under certain limits.
+
+=for :list
+* C<max_items> - Maximum number of historical entries to keep (default: value of L</history_max_items>, no
+ limit: -1)
+* C<max_size> - Maximum total size (in bytes) of historical entries to keep (default: value of
+ L</history_max_size>, no limit: -1)
+* C<max_age> - Maximum age (in days) of historical entries to keep (default: 365, no limit: -1)
+
+=cut
+
+sub prune_history {
+ my $self = shift;
+ my %args = @_;
+
+ my $max_items = $args{max_items} // $self->history_max_items // HISTORY_DEFAULT_MAX_ITEMS;
+ my $max_size = $args{max_size} // $self->history_max_size // HISTORY_DEFAULT_MAX_SIZE;
+ my $max_age = $args{max_age} // $self->maintenance_history_days // HISTORY_DEFAULT_MAX_AGE;
+
+ my @removed;
+ $self->entries->each(sub {
+ push @removed, $_->prune_history(
+ max_items => $max_items,
+ max_size => $max_size,
+ max_age => $max_age,
+ );
+ });
+ return @removed;
+}
+
=method randomize_seeds
$kdbx->randomize_seeds;
$key = $kdbx->key($primitive);
Get or set a L<File::KDBX::Key>. This is the master key (e.g. a password or a key file that can decrypt
-a database). See L<File::KDBX::Key/new> for an explanation of what the primitive can be.
+a database). You can also pass a primitive castable to a B<Key>. See L<File::KDBX::Key/new> for an explanation
+of what the primitive can be.
You generally don't need to call this directly because you can provide the key directly to the loader or
dumper when loading or dumping a KDBX file.
$key = $kdbx->composite_key($key);
$key = $kdbx->composite_key($primitive);
-Construct a L<File::KDBX::Key::Composite> from a primitive. See L<File::KDBX::Key/new> for an explanation of
-what the primitive can be. If the primitive does not represent a composite key, it will be wrapped.
+Construct a L<File::KDBX::Key::Composite> from a B<Key> or primitive. See L<File::KDBX::Key/new> for an
+explanation of what the primitive can be. If the primitive does not represent a composite key, it will be
+wrapped.
-You generally don't need to call this directly. The parser and writer use it to transform a master key into
+You generally don't need to call this directly. The loader and dumper use it to transform a master key into
a raw encryption key.
=cut
If not passed, the UUID comes from C<< $kdbx->headers->{cipher_id} >> and the encryption IV comes from
C<< $kdbx->headers->{encryption_iv} >>.
-You generally don't need to call this directly. The parser and writer use it to decrypt and encrypt KDBX
+You generally don't need to call this directly. The loader and dumper use it to decrypt and encrypt KDBX
files.
=cut
C<< $kdbx->inner_headers->{inner_random_stream_key} >> and
C<< $kdbx->inner_headers->{inner_random_stream_id} >> (respectively) for KDBX4 files.
-You generally don't need to call this directly. The parser and writer use it to scramble protected strings.
+You generally don't need to call this directly. The loader and dumper use it to scramble protected strings.
=cut
#########################################################################################
-# sub check {
-# - Fixer tool. Can repair inconsistencies, including:
-# - Orphaned binaries... not really a thing anymore since we now distribute binaries amongst entries
-# - Unused custom icons (OFF, data loss)
-# - Duplicate icons
-# - All data types are valid
-# - date times are correct
-# - boolean fields
-# - All UUIDs refer to things that exist
-# - previous parent group
-# - recycle bin
-# - last selected group
-# - last visible group
-# - Enforce history size limits (ON)
-# - Check headers/meta (ON)
-# - Duplicate deleted objects (ON)
-# - Duplicate window associations (OFF)
-# - Only one root group (ON)
- # - Header UUIDs match known ciphers/KDFs?
-# }
-
-#########################################################################################
-
sub _handle_signal {
my $self = shift;
my $object = shift;
#########################################################################################
+=attr sig1
+
+=attr sig2
+
+=attr version
+
+=attr headers
+
+=attr inner_headers
+
+=attr meta
+
+=attr binaries
+
+=attr deleted_objects
+
+Hash of UUIDs for objects that have been deleted. This includes groups, entries and even custom icons.
+
+=attr raw
+
+Bytes contained within the encrypted layer of a KDBX file. This is only set when using
+L<File::KDBX::Loader::Raw>.
+
=attr comment
A text string associated with the database. Often unset.
The UUID of a cipher used to encrypt the database when stored as a file.
-See L</File::KDBX::Cipher>.
+See L<File::KDBX::Cipher>.
=attr compression_flags
Timestamp indicating when the default username was last changed.
-=attr maintenance_history_days
-
-TODO... not really sure what this is. 😀
-
=attr color
A color associated with the database (in the form C<#ffffff> where "f" is a hexidecimal digit). Some agents
Number of days until the agent should prompt to force changing the master key.
Note: This is purely advisory. It is up to the individual agent software to actually enforce it.
-C<File::KDBX> does NOT enforce it.
+B<File::KDBX> does NOT enforce it.
+
+=attr custom_icons
+
+Array of custom icons that can be associated with groups and entries.
+
+This list can be managed with the methods L</add_custom_icon> and L</remove_custom_icon>.
=attr recycle_bin_enabled
=attr recycle_bin_changed
-Timestamp indicating when the recycle bin was last changed.
+Timestamp indicating when the recycle bin group was last changed.
=attr entry_templates_group
=attr history_max_items
-The maximum number of historical entries allowed to be saved for each entry.
+The maximum number of historical entries that should be kept for each entry. Default is 10.
=attr history_max_size
-The maximum total size (in bytes) that each individual entry's history is allowed to grow.
+The maximum total size (in bytes) that each individual entry's history is allowed to grow. Default is 6 MiB.
+
+=attr maintenance_history_days
+
+The maximum age (in days) historical entries should be kept. Default it 365.
=attr settings_changed
use File::KDBX;
+ # Create a new database from scratch
my $kdbx = File::KDBX->new;
+ # Add some objects to the database
my $group = $kdbx->add_group(
name => 'Passwords',
);
-
my $entry = $group->add_entry(
title => 'My Bank',
+ username => 'mreynolds',
password => 's3cr3t',
);
- $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
+ # Save the database to the filesystem
+ $kdbx->dump_file('passwords.kdbx', 'masterpw changeme');
- $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
+ # Load the database from the filesystem into a new database instance
+ my $kdbx2 = File::KDBX->load_file('passwords.kdbx', 'masterpw changeme');
- kdbx->entries->each(sub {
- my ($entry) = @_;
+ # Iterate over database entries, print entry titles
+ $kdbx2->entries->each(sub($entry, @) {
say 'Entry: ', $entry->title;
});
+See L</RECIPES> for more examples.
+
=head1 DESCRIPTION
-B<File::KDBX> provides everything you need to work with a KDBX database. A KDBX database is a hierarchical
+B<File::KDBX> provides everything you need to work with KDBX databases. A KDBX database is a hierarchical
object database which is commonly used to store secret information securely. It was developed for the KeePass
-password safe. See L</"KDBX Introduction"> for more information about KDBX.
+password safe. See L</"Introduction to KDBX"> for more information about KDBX.
-This module lets you query entries, create new entries, delete entries and modify entries. The distribution
-also includes various parsers and generators for serializing and persisting databases.
+This module lets you query entries, create new entries, delete entries, modify entries and more. The
+distribution also includes various parsers and generators for serializing and persisting databases.
-This design of this software was influenced by the L<KeePassXC|https://github.com/keepassxreboot/keepassxc>
+The design of this software was influenced by the L<KeePassXC|https://github.com/keepassxreboot/keepassxc>
implementation of KeePass as well as the L<File::KeePass> module. B<File::KeePass> is an alternative module
that works well in most cases but has a small backlog of bugs and security issues and also does not work with
newer KDBX version 4 files. If you're coming here from the B<File::KeePass> world, you might be interested in
L<File::KeePass::KDBX> that is a drop-in replacement for B<File::KeePass> that uses B<File::KDBX> for storage.
-=head2 KDBX Introduction
+This software is a B<pre-1.0 release>. The interface should be considered pretty stable, but there might be
+minor changes up until a 1.0 release. Breaking changes will be noted in the F<Changes> file.
-A KDBX database consists of a hierarchical I<group> of I<entries>. Entries can contain zero or more key-value
-pairs of I<strings> and zero or more I<binaries> (i.e. octet strings). Groups, entries, strings and binaries:
-that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is associated with each entry, group
-and the database as a whole.
+=head2 Features
+
+=for :list
+* ☑ Read and write KDBX version 3 - version 4.1
+* ☑ Read and write KDB files (requires L<File::KeePass>)
+* ☑ Unicode character strings
+* ☑ L</"Simple Expression"> Searching
+* ☑ L<Placeholders|File::KDBX::Entry/Placeholders> and L<field references|/resolve_reference>
+* ☑ L<One-time passwords|File::KDBX::Entry/"One-time Passwords">
+* ☑ L<Very secure|/SECURITY>
+* ☑ L</"Memory Protection">
+* ☑ Challenge-response key components, like L<YubiKey|File::KDBX::Key::YubiKey>
+* ☑ Variety of L<key file|File::KDBX::Key::File> types: binary, hexed, hashed, XML v1 and v2
+* ☑ Pluggable registration of different kinds of ciphers and key derivation functions
+* ☑ Built-in database maintenance functions
+* ☑ Pretty fast, with L<XS optimizations|File::KDBX::XS> available
+* ☒ Database synchronization / merging (not yet)
+
+=head2 Introduction to KDBX
+
+A KDBX database consists of a tree of I<groups> and I<entries>, with a single I<root> group. Entries can
+contain zero or more key-value pairs of I<strings> and zero or more I<binaries> (i.e. octet strings). Groups,
+entries, strings and binaries: that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is
+associated with each entry, group and the database as a whole.
You can think of a KDBX database kind of like a file system, where groups are directories, entries are files,
and strings and binaries make up a file's contents.
-Databases are typically persisted as a encrypted, compressed files. They are usually accessed directly (i.e.
+Databases are typically persisted as encrypted, compressed files. They are usually accessed directly (i.e.
not over a network). The primary focus of this type of database is data security. It is ideal for storing
relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as
have the correct I<master key>. Even if the database file were to be "leaked" to the public Internet, it
-should be virtually impossible to crack with a strong key. See L</SECURITY> for an overview of security
-considerations.
+should be virtually impossible to crack with a strong key. The KDBX format is most often used by password
+managers to store passwords so that users can know a single strong password and not have to reuse passwords
+across different websites. See L</SECURITY> for an overview of security considerations.
=head1 RECIPES
=head2 Read an existing database
my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
- $kdbx->unlock;
+ $kdbx->unlock; # cause $entry->password below to be defined
- $kdbx->entries->each(sub {
- my ($entry) = @_;
- say 'Found password for ', $entry->title;
+ $kdbx->entries->each(sub($entry, @) {
+ say 'Found password for: ', $entry->title;
say ' Username: ', $entry->username;
say ' Password: ', $entry->password;
});
Recycle all entries with the string "too old" appearing in the B<Notes> string.
+=head2 Remove empty groups
+
+ $kdbx->groups(algorithm => 'dfs')
+ ->where(-true => 'is_empty')
+ ->each('remove');
+
+With the search/iteration C<algorithm> set to "dfs", groups will be ordered deepest first and the root group
+will be last. This allows removing groups that only contain empty groups.
+
+This can also be done with one call to L</remove_empty_groups>.
+
=head1 SECURITY
One of the biggest threats to your database security is how easily the encryption key can be brute-forced.
-Strong brute-force protection depends on a couple factors:
+Strong brute-force protection depends on:
=for :list
* Using unguessable passwords, passphrases and key files.
For one thing, the encryption key is stored in the same address space. If core is dumped, the encryption key
is available to be found out. But at least there is the chance that the encryption key and the encrypted
-secrets won't both be paged out while memory-constrained.
+secrets won't both be paged out together while memory-constrained.
Another problem is that some perls (somewhat notoriously) copy around memory behind the scenes willy nilly,
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
To find things in a KDBX database, you should use a filtered iterator. If you have an iterator, such as
returned by L</entries>, L</groups> or even L</objects> you can filter it using L<File::KDBX::Iterator/where>.
- my $filtered_results = $kdbx->entries->where($query);
+ my $filtered_entries = $kdbx->entries->where(\&query);
-A C<$query> is just a subroutine that you can either write yourself or have generated for you from either
+A C<\&query> is just a subroutine that you can either write yourself or have generated for you from either
a L</"Simple Expression"> or L</"Declarative Syntax">. It's easier to have your query generated, so I'll cover
that first.
my $entries = $kdbx->entries->where(\'canyon', qw[title]);
-Notice the first argument is a B<scalarref>. This diambiguates a simple expression from other types of queries
-covered below.
+Notice the first argument is a B<scalarref>. This disambiguates a simple expression from other types of
+queries covered below.
As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that
has the words "red" B<and> "canyon" anywhere in the title:
my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);
-To search over multiple fields simultaneously, just list them. To search for entries with "grocery" in the
-title or notes but not "Foodland":
+To search over multiple fields simultaneously, just list them all. To search for entries with "grocery" (but
+not "Foodland") in the title or notes:
my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);
my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);
-It helps to read it right-to-left, like "usage_count is >= 5".
+It helps to read it right-to-left, like "usage_count is greater than or equal to 5".
If you find the disambiguating structures to be distracting or confusing, you can also the
L<File::KDBX::Util/simple_expression_query> function as a more intuitive alternative. The following example is
=head2 Declarative Syntax
Structuring a declarative query is similar to L<SQL::Abstract/"WHERE CLAUSES">, but you don't have to be
-familiar with that module. Just learn by examples.
+familiar with that module. Just learn by examples here.
To search for all entries in a database titled "My Bank":
username => 'neo',
]);
-
-
You can use different operators to test different types of attributes. The L<File::KDBX::Entry/icon_id>
attribute is a number, so we should use a number comparison operator. To find entries using the smartphone
icon:
* C<==> - Number equal
* C<!=> - Number not equal
* C<< < >> - Number less than
-* C<< > >>> - Number greater than
+* C<< > >> - Number greater than
* C<< <= >> - Number less than or equal
* C<< >= >> - Number less than or equal
* C<=~> - String match regular expression
'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
},
);
- if (1 < $groups->count) { say "Problem: there can be only one!" }
-Note: L<File::KDBX::Util/uuid> is a little helper function to convert a UUID in its pretty form into bytes.
-This helper function isn't special to this example or to queries generally. It could have been written with
+Note: L<File::KDBX::Util/uuid> is a little utility function to convert a UUID in its pretty form into bytes.
+This utility function isn't special to this example or to queries generally. It could have been written with
a literal such as C<"\x59\x6f\x75\x20\x61...">, but that's harder to read.
Notice we searched for groups this time. Finding groups works exactly the same as it does for entries.
Notice also that we didn't wrap the query in hashref curly-braces or arrayref square-braces. Those are
-optional. By default it will only match ALL attributes (as if there were curly-braces), but it doesn't matter
-if there is only one attribute so it's fine to rely on the implicit behavior.
+optional. By default it will only match ALL attributes (as if there were curly-braces).
Testing the truthiness of an attribute is a little bit different because it isn't a binary operation. To find
all entries with the password quality check disabled:
weird for your taste):
my $entries = $kdbx->entries->where('!!' => 'quality_check');
- my $entries = $kdbx->entries->where(-true => 'quality_check');
+ my $entries = $kdbx->entries->where(-true => 'quality_check'); # same thing
Yes, there is also a C<-false> and a C<-not> if you prefer one of those over C<!>. C<-false> and C<-not>
(along with C<-true>) are also special in that you can use them to invert the logic of a subquery. These are
criteria you want and return true if it matches or false to skip. To do this, just pass your subroutine
coderef to C<where>.
-For example, these are all equivalent to find all entries in the database titled "My Bank":
+To review the different types of queries, these are all equivalent to find all entries in the database titled
+"My Bank":
my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]); # simple expression
my $entries = $kdbx->entries->where(title => 'My Bank'); # declarative syntax
}
}
+=head2 Iteration
+
+Iterators are the built-in way to navigate or walk the database tree. You get an iterator from L</entries>,
+L</groups> and L</objects>. You can specify the search algorithm to iterate over objects in different orders
+using the C<algorithm> option, which can be one of these L<constants|File::KDBX::Constants/":iteration">:
+
+=for :list
+* C<ITERATION_IDS> - Iterative deepening search (default)
+* C<ITERATION_DFS> - Depth-first search
+* C<ITERATION_BFS> - Breadth-first search
+
+When iterating over objects generically, groups always precede their direct entries (if any). When the
+C<history> option is used, current entries always precede historical entries.
+
+If you have a database tree like this:
+
+ Database
+ - Root
+ - Group1
+ - EntryA
+ - Group2
+ - EntryB
+ - Group3
+ - EntryC
+
+=for :list
+* IDS order of groups is: Root, Group1, Group2, Group3
+* IDS order of entries is: EntryA, EntryB, EntryC
+* IDS order of objects is: Root, Group1, EntryA, Group2, EntryB, Group3, EntryC
+* DFS order of groups is: Group2, Group1, Group3, Root
+* DFS order of entries is: EntryB, EntryA, EntryC
+* DFS order of objects is: Group2, EntryB, Group1, EntryA, Group3, EntryC, Root
+* BFS order of groups is: Root, Group1, Group3, Group2
+* BFS order of entries is: EntryA, EntryC, EntryB
+* BFS order of objects is: Root, Group1, EntryA, Group3, EntryC, Group2, EntryB
+
+=head1 SYNCHRONIZING
+
+B<TODO> - This is a planned feature, not yet implemented.
+
=head1 ERRORS
Errors in this package are constructed as L<File::KDBX::Error> objects and propagated using perl's built-in
-mechanisms. Fatal errors are propagated using L<functions/die> and non-fatal errors (a.k.a. warnings) are
-propagated using L<functions/warn> while adhering to perl's L<warnings> system. If you're already familiar
-with these mechanisms, you can skip this section.
+mechanisms. Fatal errors are propagated using L<perlfunc/"die LIST"> and non-fatal errors (a.k.a. warnings)
+are propagated using L<perlfunc/"warn LIST"> while adhering to perl's L<warnings> system. If you're already
+familiar with these mechanisms, you can skip this section.
-You can catch fatal errors using L<functions/eval> (or something like L<Try::Tiny>) and non-fatal errors using
-C<$SIG{__WARN__}> (see L<variables/%SIG>). Examples:
+You can catch fatal errors using L<perlfunc/"eval BLOCK"> (or something like L<Try::Tiny>) and non-fatal
+errors using C<$SIG{__WARN__}> (see L<perlvar/%SIG>). Examples:
use File::KDBX::Error qw(error);
* C<PERL_ONLY> - Do not use L<File::KDBX::XS> if true (default: false)
* C<NO_FORK> - Do not fork if true (default: false)
-=head1 CAVEATS
-
-Some features (e.g. parsing) require 64-bit perl. It should be possible and actually pretty easy to make it
-work using L<Math::BigInt>, but I need to build a 32-bit perl in order to test it and frankly I'm still
-figuring out how. I'm sure it's simple so I'll mark this one "TODO", but for now an exception will be thrown
-when trying to use such features with undersized IVs.
-
=head1 SEE ALSO
-L<File::KeePass> is a much older alternative. It's good but has a backlog of bugs and lacks support for newer
-KDBX features.
-
-=attr sig1
-
-=attr sig2
-
-=attr version
+=for :list
+* L<KeePass Password Safe|https://keepass.info/> - The original KeePass
+* L<KeePassXC|https://keepassxc.org/> - Cross-Platform Password Manager written in C++
+* L<File::KeePass> has overlapping functionality. It's good but has a backlog of some pretty critical bugs and
+ lacks support for newer KDBX features.
-=attr headers
+=begin :header
-=attr inner_headers
+=begin markdown
-=attr meta
+[](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml)
+[](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml)
+[](https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml)
-=attr binaries
+=end markdown
-=attr deleted_objects
+=begin HTML
-=attr raw
+<a title="Linux" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/linux.yml/badge.svg"></a>
+<a title="macOS" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/macos.yml/badge.svg"></a>
+<a title="Windows" href="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml"><img src="https://github.com/chazmcgarvey/File-KDBX/actions/workflows/windows.yml/badge.svg"></a>
- $value = $kdbx->$attr;
- $kdbx->$attr($value);
+=end HTML
-Get and set attributes.
+=end :header
=cut
projects / chaz / p5-File-KDBX / blobdiff