VERSION
- version 0.900
+ version 0.906
SYNOPSIS
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;
});
comment
- A text string associated with the database. Often unset.
+ A text string associated with the database stored unencrypted in the
+ file header. Often unset.
cipher_id
The UUID of a cipher used to encrypt the database when stored as a
file.
- See "File::KDBX::Cipher".
+ See File::KDBX::Cipher.
compression_flags
transform_rounds
The number of rounds or iterations used in the key derivation function.
- Increasing this number makes loading and saving the database slower by
- design in order to make dictionary and brute force attacks more costly.
+ Increasing this number makes loading and saving the database slower in
+ order to make dictionary and brute force attacks more costly.
encryption_iv
was introduced with KDBX4.
This method never returns less than KDBX_VERSION_3_1 (i.e. 0x00030001).
- That file version is so ubiquitious and well-supported, there are
- seldom reasons to dump in a lesser format nowadays.
+ That file version is so ubiquitous and well-supported, there are seldom
+ reasons to dump in a lesser format nowadays.
WARNING: If you dump a database with a minimum version higher than the
current "version", the dumper will typically issue a warning and
$kdbx->add_entry($entry, %options);
$kdbx->add_entry(%entry_attributes, %options);
- Add a entry to a database. This is equivalent to identifying a parent
+ Add an entry to a database. This is equivalent to identifying a parent
group and calling "add_entry" in File::KDBX::Group on the parent group,
forwarding the arguments. Available options:
$kdbx->lock;
- Encrypt all protected binaries strings in a database. The encrypted
- strings are stored in a File::KDBX::Safe associated with the database
- and the actual strings will be replaced with undef to indicate their
+ Encrypt all protected strings and binaries in a database. The encrypted
+ data is stored in a File::KDBX::Safe associated with the database and
+ the actual values will be replaced with undef to indicate their
protected state. Returns itself to allow method chaining.
- You can call code on an already-locked database to memory-protect any
+ You can call lock on an already-locked database to memory-protect any
unprotected strings and binaries added after the last time the database
was locked.
$kdbx->unlock;
- Decrypt all protected strings in a database, replacing undef
- placeholders with unprotected values. Returns itself to allow method
- chaining.
+ Decrypt all protected strings and binaries in a database, replacing
+ undef value placeholders with their actual, unprotected values. Returns
+ itself to allow method chaining.
unlock_scoped
See "lock" and "unlock".
+ Example:
+
+ {
+ my $guard = $kdbx->unlock_scoped;
+ ...;
+ }
+ # $kdbx is now memory-locked
+
peek
$string = $kdbx->peek(\%string);
$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 undef values) until "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 undef values) until "unlock" is called.
remove_empty_groups
keep (default: value of "history_max_size", no limit: -1)
* max_age - Maximum age (in days) of historical entries to keep
- (default: 365, no limit: -1)
+ (default: value of "maintenance_history_days", no limit: -1)
randomize_seeds
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.
+ this method explicitly because the dumper does it for you by default.
key
Get or set a File::KDBX::Key. This is the master key (e.g. a password
or a key file that can decrypt a database). You can also pass a
- primitive that can be cast to a Key. See "new" in File::KDBX::Key for
- an explanation of what the primitive can be.
+ primitive castable to a Key. See "new" in File::KDBX::Key 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
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;
master keys. It is up to you to pick or 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
+ idea is that you want each single 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
really expensive.
equal to 5".
If you find the disambiguating structures to be distracting or
- confusing, you can also the "simple_expression_query" in
+ confusing, you can also use the "simple_expression_query" in
File::KDBX::Util function as a more intuitive alternative. The
following example is equivalent to the previous:
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 pair where the key is the name
+ 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 "entries", "groups" and "objects". You can
specify the search algorithm to iterate over objects in different
- orders using the algorith option, which can be one of these constants:
+ orders using the algorithm option, which can be one of these constants:
* ITERATION_IDS - Iterative deepening search (default)
Errors in this package are constructed as File::KDBX::Error objects and
propagated using perl's built-in mechanisms. Fatal errors are
- propagated using "die" in functions and non-fatal errors (a.k.a.
- warnings) are propagated using "warn" in functions while adhering to
- perl's warnings system. If you're already familiar with these
+ propagated using "die LIST" in perlfunc and non-fatal errors (a.k.a.
+ warnings) are propagated using "warn LIST" in perlfunc while adhering
+ to perl's warnings system. If you're already familiar with these
mechanisms, you can skip this section.
- You can catch fatal errors using "eval" in functions (or something like
- Try::Tiny) and non-fatal errors using $SIG{__WARN__} (see "%SIG" in
- variables). Examples:
+ You can catch fatal errors using "eval BLOCK" in perlfunc (or something
+ like Try::Tiny) and non-fatal errors using $SIG{__WARN__} (see "%SIG"
+ in perlvar). Examples:
use File::KDBX::Error qw(error);
* NO_FORK - Do not fork if true (default: false)
-CAVEATS
-
- Some features (e.g. parsing) require 64-bit perl. It should be possible
- and actually pretty easy to make it work using 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.
-
SEE ALSO
* KeePass Password Safe <https://keepass.info/> - The original
projects / chaz / p5-File-KDBX / blobdiff