package File::KDBX;
# ABSTRACT: Encrypted database to store secret text and files
+use 5.010;
use warnings;
use strict;
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;
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
my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
my $base = delete $args{base} // $self->root;
- return $base->groups_deeply(%args);
+ return $base->all_groups(%args);
}
##############################################################################
$kdbx->add_entry($entry, %options);
$kdbx->add_entry(%entry_attributes, %options);
-Add a entry to a database. This is equivalent to identifying a parent group and calling
+Add an entry to a database. This is equivalent to identifying a parent group and calling
L<File::KDBX::Group/add_entry> on the parent group, forwarding the arguments. Available options:
=for :list
my %args = @_ % 2 == 0 ? @_ : (base => shift, @_);
my $base = delete $args{base} // $self->root;
- return $base->entries_deeply(%args);
+ return $base->all_entries(%args);
}
##############################################################################
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 }
* L</transform_seed>
Randomizing these values has no effect on a loaded database. These are only used when a database is dumped.
-You normally do not need to call this method explicitly because the dumper does it explicitly by default.
+You normally do not need to call this method explicitly because the dumper does it for you by default.
=cut
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
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
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;
});
my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
$kdbx->unlock; # cause $entry->password below to be defined
- $kdbx->entries->each(sub {
- my ($entry) = @_;
+ $kdbx->entries->each(sub($entry, @) {
say 'Found password for: ', $entry->title;
say ' Username: ', $entry->username;
say ' Password: ', $entry->password;
generate strong keys.
The KDBX format allows for the key derivation function to be tuned. The idea is that you want each single
-brute-foce attempt to be expensive (in terms of time, CPU usage or memory usage), so that making a lot of
+brute-force attempt to be expensive (in terms of time, CPU usage or memory usage), so that making a lot of
attempts (which would be required if you have a strong master key) gets I<really> expensive.
How expensive you want to make each attempt is up to you and can depend on the application.
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
+If you find the disambiguating structures to be distracting or confusing, you can also use the
L<File::KDBX::Util/simple_expression_query> function as a more intuitive alternative. The following example is
equivalent to the previous:
Note: L<File::KDBX::Constants/ICON_SMARTPHONE> is just a constant from L<File::KDBX::Constants>. It isn't
special to this example or to queries generally. We could have just used a literal number.
-The important thing to notice here is how we wrapped the condition in another arrayref with a single key-value
+The important thing to notice here is how we wrapped the condition in another hashref with a single key-value
pair where the key is the name of an operator and the value is the thing to match against. The supported
operators are:
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<algorith> option, which can be one of these L<constants|File::KDBX::Constants/":iteration">:
+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<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
=for :list
projects / chaz / p5-File-KDBX / blobdiff