# VERSION
-version 0.900
+version 0.906
# SYNOPSIS
```perl
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"](#file-kdbx-cipher).
+See [File::KDBX::Cipher](https://metacpan.org/pod/File%3A%3AKDBX%3A%3ACipher).
## 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.
+and saving the database slower in order to make dictionary and brute force attacks more costly.
## encryption\_iv
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.
-`File::KDBX` does NOT enforce it.
+**File::KDBX** does NOT enforce it.
## custom\_icons
least `KDBX_VERSION_4_0` (i.e. `0x00040000`) because Argon2 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.
+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"](#version), the dumper will
typically issue a warning and automatically upgrade the database. This seems like the safest behavior in order
$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
["add\_entry" in File::KDBX::Group](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AGroup#add_entry) on the parent group, forwarding the arguments. Available options:
- `group` - Group object or group UUID to add the entry to (default: root group)
$kdbx->lock;
```
-Encrypt all protected binaries strings in a database. The encrypted strings are stored in
-a [File::KDBX::Safe](https://metacpan.org/pod/File%3A%3AKDBX%3A%3ASafe) associated with the database and the actual strings will be replaced with `undef` to
+Encrypt all protected strings and binaries in a database. The encrypted data is stored in
+a [File::KDBX::Safe](https://metacpan.org/pod/File%3A%3AKDBX%3A%3ASafe) 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 unprotected strings and binaries
+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.
## unlock
$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"](#lock) and ["unlock"](#unlock).
+Example:
+
+```perl
+{
+ my $guard = $kdbx->unlock_scoped;
+ ...;
+}
+# $kdbx is now memory-locked
+```
+
## peek
```
$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"](#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"](#unlock) is called.
## remove\_empty\_groups
- `max_items` - Maximum number of historical entries to keep (default: value of ["history\_max\_items"](#history_max_items), no limit: -1)
- `max_size` - Maximum total size (in bytes) of historical entries to keep (default: value of ["history\_max\_size"](#history_max_size), no limit: -1)
-- `max_age` - Maximum age (in days) of historical entries to keep (default: 365, no limit: -1)
+- `max_age` - Maximum age (in days) of historical entries to keep (default: value of ["maintenance\_history\_days"](#maintenance_history_days), no limit: -1)
## randomize\_seeds
- ["transform\_seed"](#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.
## key
```
Get or set a [File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey). 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](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey#new) for an
-explanation of what the primitive can be.
+a database). You can also pass a primitive castable to a **Key**. See ["new" in File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey#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.
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 _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
["simple\_expression\_query" in File::KDBX::Util](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AUtil#simple_expression_query) function as a more intuitive alternative. The following example is
equivalent to the previous:
Note: ["ICON\_SMARTPHONE" in File::KDBX::Constants](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AConstants#ICON_SMARTPHONE) is just a constant from [File::KDBX::Constants](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AConstants). 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 ["entries"](#entries),
["groups"](#groups) and ["objects"](#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](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AConstants#iteration):
+using the `algorithm` option, which can be one of these [constants](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AConstants#iteration):
- `ITERATION_IDS` - Iterative deepening search (default)
- `ITERATION_DFS` - Depth-first search
# ERRORS
Errors in this package are constructed as [File::KDBX::Error](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AError) objects and propagated using perl's built-in
-mechanisms. Fatal errors are propagated using ["die" in functions](https://metacpan.org/pod/functions#die) and non-fatal errors (a.k.a. warnings) are
-propagated using ["warn" in functions](https://metacpan.org/pod/functions#warn) while adhering to perl's [warnings](https://metacpan.org/pod/warnings) system. If you're already familiar
-with these mechanisms, you can skip this section.
+mechanisms. Fatal errors are propagated using ["die LIST" in perlfunc](https://metacpan.org/pod/perlfunc#die-LIST) and non-fatal errors (a.k.a. warnings)
+are propagated using ["warn LIST" in perlfunc](https://metacpan.org/pod/perlfunc#warn-LIST) while adhering to perl's [warnings](https://metacpan.org/pod/warnings) system. If you're already
+familiar with these mechanisms, you can skip this section.
-You can catch fatal errors using ["eval" in functions](https://metacpan.org/pod/functions#eval) (or something like [Try::Tiny](https://metacpan.org/pod/Try%3A%3ATiny)) and non-fatal errors using
-`$SIG{__WARN__}` (see ["%SIG" in variables](https://metacpan.org/pod/variables#SIG)). Examples:
+You can catch fatal errors using ["eval BLOCK" in perlfunc](https://metacpan.org/pod/perlfunc#eval-BLOCK) (or something like [Try::Tiny](https://metacpan.org/pod/Try%3A%3ATiny)) and non-fatal
+errors using `$SIG{__WARN__}` (see ["%SIG" in perlvar](https://metacpan.org/pod/perlvar#SIG)). Examples:
```perl
use File::KDBX::Error qw(error);
- `PERL_ONLY` - Do not use [File::KDBX::XS](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AXS) if true (default: false)
- `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](https://metacpan.org/pod/Math%3A%3ABigInt), 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 KeePass
projects / chaz / p5-File-KDBX / blobdiff