{{$NEXT}}
+ * Remove min_version methods from dumper and loader
+
0.800 2022-04-30 21:14:30-0600
* Initial release
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 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
=head2 Features
-This implementation of KDBX supports a lot of 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<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>
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
- Group3
- EntryC
-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
+=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
$dumper = $dumper->reset;
-Set a L<File::KDBX::Dumper> to a blank state, ready to dumper another KDBX file.
+Set a L<File::KDBX::Dumper> to a blank state, ready to dump another KDBX file.
=cut
Dump a KDBX file.
-The C<$key> is either a L<File::KDBX::Key> or a primitive that can be converted to a Key object.
+The C<$key> is either a L<File::KDBX::Key> or a primitive that can be cast to a Key object.
=cut
$dumper->dump_handle($fh, $key);
$dumper->dump_handle(*IO, $key);
-Dump a KDBX file to an input stream / file handle.
+Dump a KDBX file to an output stream / file handle.
=cut
has 'allow_upgrade', is => 'ro', default => 1;
has 'randomize_seeds', is => 'ro', default => 1;
-=method min_version
-
- $min_version = File::KDBX::Dumper->min_version;
-
-Get the minimum KDBX file version supported, which is 3.0 or C<0x00030000> as
-it is encoded.
-
-To generate older KDBX files unsupported by this module, try L<File::KeePass>.
-
-=cut
-
-sub min_version { KDBX_VERSION_OLDEST }
-
sub _fh { $_[0]->{fh} or throw 'IO handle not set' }
sub _dump {
my $kdbx = $self->kdbx;
$kdbx->sig1 == KDBX_SIG1 or throw 'Invalid file signature', sig1 => $kdbx->sig1;
- $kdbx->version < $self->min_version || KDBX_VERSION_LATEST < $kdbx->version
+ $kdbx->version < KDBX_VERSION_OLDEST || KDBX_VERSION_LATEST < $kdbx->version
and throw 'Unsupported file version', version => $kdbx->version;
my @magic = ($kdbx->sig1, $kdbx->sig2, $kdbx->version);
format uses HMAC-SHA256 to detect tampering.
L<File::KDBX::Dumper::V3> automatically calculates the header hash an provides it to this module, and plain
-XML files which don't have a KDBX wrapper don't have headers and so should have a header hash. Therefore there
-is probably never any reason to set this manually.
+XML files which don't have a KDBX wrapper don't have headers and so should not have a header hash. Therefore
+there is probably never any reason to set this manually.
=cut
my %PLACEHOLDERS;
my %STANDARD_STRINGS = map { $_ => 1 } qw(Title UserName Password URL Notes);
-=attr uuid
-
-128-bit UUID identifying the entry within the database.
-
-=attr icon_id
-
-Integer representing a default icon. See L<File::KDBX::Constants/":icon"> for valid values.
-
-=attr custom_icon_uuid
-
-128-bit UUID identifying a custom icon within the database.
-
=attr foreground_color
Text color represented as a string of the form C<#000000>.
TODO
-=attr tags
-
-Text string with arbitrary tags which can be used to build a taxonomy.
-
=attr auto_type_enabled
Whether or not the entry is eligible to be matched for auto-typing.
Keystroke sequences can have </Placeholders>, most commonly C<{USERNAME}> and C<{PASSWORD}>.
-=attr previous_parent_group
-
-128-bit UUID identifying a group within the database.
-
=attr quality_check
Boolean indicating whether the entry password should be tested for weakness and show up in reports.
There are methods available to provide more convenient access to binaries, including L</binary> and
L</binary_value>.
-=attr custom_data
-
-A set of key-value pairs used to store arbitrary data, usually used by software to keep track of state rather
-than by end users (who typically work with the strings and binaries).
-
=attr history
Array of historical entries. Historical entries are prior versions of the same entry so they all share the
same UUID with the current entry.
-=attr last_modification_time
-
-Date and time when the entry was last modified.
-
-=attr creation_time
-
-Date and time when the entry was created.
-
-=attr last_access_time
-
-Date and time when the entry was last accessed.
-
-=attr expiry_time
-
-Date and time when the entry expired or will expire.
-
-=attr expires
-
-Boolean value indicating whether or not an entry is expired.
-
-=attr usage_count
-
-The number of times an entry has been used, which typically means how many times the B<Password> string has
-been accessed.
-
-=attr location_changed
-
-Date and time when the entry was last moved to a different parent group.
-
=attr notes
Alias for the B<Notes> string value.
* ☑ C<{DT_UTC_MINUTE}> Minute Year component of the current UTC time
* ☑ C<{DT_UTC_SECOND}> - Second component of the current UTC time
-If the current date and time is <2012-07-25 17:05:34>, the "simple" form would be C<20120725170534>.
+If the current date and time is C<2012-07-25 17:05:34>, the "simple" form would be C<20120725170534>.
=head3 Special Key Placeholders
If the placeholder is expanded in the context of an entry, C<$entry> is the B<File::KDBX::Entry> object in
context. Otherwise it is C<undef>. An entry is in context if, for example, the placeholder is in an entry's
-strings or auto-complete key sequences.
+strings or auto-type key sequences.
$File::KDBX::PLACEHOLDERS{'MY_PLACEHOLDER:'} = sub {
my ($entry, $arg) = @_; # ^ Notice the colon here
our $VERSION = '999.999'; # VERSION
-=attr uuid
-
-128-bit UUID identifying the group within the database.
-
=attr name
The human-readable name of the group.
Free form text string associated with the group.
-=attr tags
-
-Text string with arbitrary tags which can be used to build a taxonomy.
-
-=attr icon_id
-
-Integer representing a default icon. See L<File::KDBX::Constants/":icon"> for valid values.
-
-=attr custom_icon_uuid
-
-128-bit UUID identifying a custom icon within the database.
-
=attr is_expanded
Whether or not subgroups are visible when listed for user selection.
The UUID of the entry visible at the top of the list.
-=attr custom_data
-
-A set of key-value pairs used to store arbitrary data, usually used by software to keep track of state rather
-than by end users (who typically work with the strings and binaries).
-
-=attr previous_parent_group
-
-128-bit UUID identifying a group within the database.
-
=attr entries
Array of entries contained within the group.
Array of subgroups contained within the group.
-=attr last_modification_time
-
-Date and time when the entry was last modified.
-
-=attr creation_time
-
-Date and time when the entry was created.
-
-=attr last_access_time
-
-Date and time when the entry was last accessed.
-
-=attr expiry_time
-
-Date and time when the entry expired or will expire.
-
-=attr expires
-
-Boolean value indicating whether or not an entry is expired.
-
-=attr usage_count
-
-TODO
-
-=attr location_changed
-
-Date and time when the entry was last moved to a different parent group.
-
=cut
# has uuid => sub { generate_uuid(printable => 1) };
\@entries = $group->entries;
-Get an array of direct entries within a group.
+Get an array of direct child entries within a group.
=cut
$bool = $group->is_entry_templates;
-Get whether or not a group is the group containing entry template of its connected database.
+Get whether or not a group is the group containing entry template in its connected database.
=cut
\&iterator = File::KDBX::Iterator->new(\&iterator);
-Blesses an iterator to augment it with buffering plus some useful utility methods.
+Bless an iterator to augment it with buffering plus some useful utility methods.
=cut
$item = $iterator->();
$item = $iterator->next(\&query);
- $item = $iterator->next([\'simple expression', @fields]);
Get the next item or C<undef> if there are no more items. If a query is passed, get the next matching item,
discarding any unmatching items before the matching item. Example:
=method unget
+ # Replace buffer:
$iterator->unget(\@items);
- $iterator->unget(...);
# OR equivalently
$iterator->(\@items);
- $iterator->(...);
-Replace the buffer or unshift one or more items to the current buffer.
+ # Unshift onto buffer:
+ $iterator->unget(@items);
+ # OR equivalently
+ $iterator->(@items);
+
+Replace the buffer (first form) or unshift one or more items to the current buffer (second form).
See L</Buffer>.
$iterator->each($method_name, ...);
-Get or act on the rest of the items. There are three forms:
+Get or act on the rest of the items. This method has three forms:
=for :list
1. Without arguments, C<each> returns a list of the rest of the items.
2. Pass a coderef to be called once per item, in order. Arguments to the coderef are the item itself (also
- C<$_>), its index number and then any extra arguments that were passed to C<each> after the coderef.
+ available as C<$_>), its index number and then any extra arguments that were passed to C<each> after the
+ coderef.
3. Pass a string that is the name of a method to be called on each object, in order. Any extra arguments
passed to C<each> after the method name are passed through to each method call. This form requires each
item be an object that C<can> the given method.
=method where
\&iterator = $iterator->grep(\&query);
- \&iterator = $iterator->grep([\'simple expression', @fields]);
Get a new iterator draining from an existing iterator but providing only items that pass a test or are matched
-by a query.
+by a query. In its basic form this method is very much like perl's built-in grep function, except for
+iterators.
+
+There are many examples of the various forms of this method at L<File::KDBX/QUERY>.
=cut
\&iterator = $iterator->map(\&code);
-Get a new iterator draining from an existing iterator but providing modified items.
+Get a new iterator draining from an existing iterator but providing modified items. In its basic form this
+method is very much like perl's built-in map function, except for iterators.
=cut
* C<collate> - If true, use B<Unicode::Collate> (if available), otherwise use perl built-ins (default: true)
* Any B<Unicode::Collate> option is also supported.
-C<sort_by> and C<order_by> are aliases.
-
B<NOTE:> This method drains the iterator completely and places the sorted items onto the buffer. See
L</CAVEATS>.
=for :list
* C<ascending> - Order ascending if true, descending otherwise (default: true)
-C<nsort_by> and C<norder_by> are aliases.
-
B<NOTE:> This method drains the iterator completely and places the sorted items onto the buffer. See
L</CAVEATS>.
Get a new iterator draining from an existing iterator but providing only a limited number of items.
-C<limit> as an alias for L<Iterator::Simple/"$iterator->head($count)">.
+C<limit> as an alias for L<< Iterator::Simple/"$iterator->head($count)" >>.
=cut
=head2 Buffer
This iterator is buffered, meaning it can drain from an iterator subroutine under the hood, storing items
-temporarily to be accessed later. This allows features like L</peek> and L</sort> which might be useful in the
-context of KDBX databases which are normally pretty small so draining an iterator isn't cost-prohibitive.
+temporarily to be accessed later. This allows features like L</peek> and L</order_by> which might be useful in
+the context of KDBX databases which are normally pretty small so draining an iterator completely isn't
+cost-prohibitive in terms of memory usage.
The way this works is that if you call an iterator without arguments, it acts like a normal iterator. If you
call it with arguments, however, the arguments are added to the buffer. When called without arguments, the
buffer is drained before the iterator function is. Using L</unget> is equivalent to calling the iterator with
-arguments, and as L</next> is equivalent to calling the iterator without arguments.
+arguments, and L</next> is equivalent to calling the iterator without arguments.
=head1 CAVEATS
$key = $key->hide;
-Put the raw key in L<File::KDBX/"Memory Protection">. Does nothing if the raw key is already in memory
-protection. Returns itself to allow method chaining.
+Put the raw key in L<memory protection|File::KDBX/"Memory Protection">. Does nothing if the raw key is already
+in memory protection. Returns itself to allow method chaining.
=cut
=for :list
* L<File::KDBX::Key::Password> - Password or passphrase, knowledge of a string of characters
-* L<File::KDBX::Key::File> - Possession of a file ("key file") with a secret.
+* L<File::KDBX::Key::File> - Possession of a file ("key file") with a secret
* L<File::KDBX::Key::ChallengeResponse> - Possession of a device that responds correctly when challenged
* L<File::KDBX::Key::YubiKey> - Possession of a YubiKey hardware device (a type of challenge-response)
* L<File::KDBX::Key::Composite> - One or more keys combined as one
B<COMPATIBILITY NOTE:> Most KeePass implementations are limited in the types and numbers of keys they support.
B<Password> keys are pretty much universally supported. B<File> keys are pretty well-supported. Many do not
support challenge-response keys. If you are concerned about compatibility, you should stick with one of these
-configurations:
+well-supported configurations:
=for :list
* One password
* One key file
-* One password and one key file
+* Composite of one password and one key file
=cut
$raw_key = $key->raw_key($challenge);
Get the raw key which is the response to a challenge. The response will be saved so that subsequent calls
-(with or without the challenge) can provide the response without challenging the responder again. Only once
+(with or without the challenge) can provide the response without challenging the responder again. Only one
response is saved at a time; if you call this with a different challenge, the new response is saved over any
previous response.
A challenge-response key is kind of like multifactor authentication, except you don't really I<authenticate>
to a KDBX database because it's not a service. Specifically it would be the "what you have" component. It
-assumes there is some device that can store a key that is only known to the unlocker of a database.
-A challenge is made to the device and the response generated based on the key is used as the raw key.
+assumes there is some device that can store a key that is only known to the owner of a database. A challenge
+is made to the device and the response generated based on the key is used as the raw key.
Inherets methods and attributes from L<File::KDBX::Key>.
$type = $key->type;
-Get the type of key file. Can be one of:
+Get the type of key file. Can be one of from L<File::KDBX::Constants/":key_file">:
=for :list
* C<KEY_FILE_TYPE_BINARY>
Load a KDBX file.
-The C<$key> is either a L<File::KDBX::Key> or a primitive that can be converted to a Key object.
+The C<$key> is either a L<File::KDBX::Key> or a primitive that can be cast to a Key object.
=cut
=for :list
* C<XML> - Read the database groups and entries as XML (default)
-* C<Raw> - Read parsing and store the result in L<File::KDBX/raw>
+* C<Raw> - Read and store the result in L<File::KDBX/raw> without parsing
=cut
has format => undef, is => 'ro';
has inner_format => 'XML', is => 'ro';
-=method min_version
-
- $min_version = File::KDBX::Loader->min_version;
-
-Get the minimum KDBX file version supported, which is 3.0 or C<0x00030000> as
-it is encoded.
-
-To read older KDBX files unsupported by this module, try L<File::KeePass>.
-
-=cut
-
-sub min_version { KDBX_VERSION_OLDEST }
-
=method read_magic_numbers
$magic = File::KDBX::Loader->read_magic_numbers($fh);
$kdbx = $object->kdbx;
$object->kdbx($kdbx);
-Get or set the L<File::KDBX> instance connected with this object.
+Get or set the L<File::KDBX> instance connected with this object. Throws if the object is disconnected. Other
+object methods might only work if the object is connected to a database and so they might also throw if the
+object is disconnected. If you're not sure if an object is connected, try L</is_connected>.
=cut
$object = $object->remove(%options);
Remove an object from its parent. If the object is a group, all contained objects stay with the object and so
-are removed as well. Options:
+are removed as well, just like cutting off a branch takes the leafs as well. Options:
=for :list
* C<signal> Whether or not to signal the removal to the connected database (default: true)
$object->custom_data(%data);
$object->custom_data(key => $value, %data);
-Get and set custom data. Custom data is metadata associated with an object.
+Get and set custom data. Custom data is metadata associated with an object. It is a set of key-value pairs
+used to store arbitrary data, usually used by software like plug-ins to keep track of state rather than by end
+users.
Each data item can have a few attributes associated with it.
# OR move an existing entry from one database to another:
$another_kdbx->add_entry($entry->remove);
+=attr uuid
+
+128-bit UUID identifying the object within the connected database.
+
+=attr icon_id
+
+Integer representing a default icon. See L<File::KDBX::Constants/":icon"> for valid values.
+
+=attr custom_icon_uuid
+
+128-bit UUID identifying a custom icon within the connected database.
+
+=attr tags
+
+Text string with arbitrary tags which can be used to build a taxonomy.
+
+=attr previous_parent_group
+
+128-bit UUID identifying a group within the connected database the previously contained the object.
+
+=attr last_modification_time
+
+Date and time when the entry was last modified.
+
+=attr creation_time
+
+Date and time when the entry was created.
+
+=attr last_access_time
+
+Date and time when the entry was last accessed.
+
+=attr expiry_time
+
+Date and time when the entry expired or will expire.
+
+=attr expires
+
+Boolean value indicating whether or not an entry is expired.
+
+=attr usage_count
+
+The number of times an entry has been used, which typically means how many times the B<Password> string has
+been accessed.
+
+=attr location_changed
+
+Date and time when the entry was last moved to a different parent group.
+
=cut
for this function, but this code is distinct, supporting an overlapping but not identical feature set and
having its own bugs.
-See L<File::KDBX/QUERY> for examples.
+See L<File::KDBX/"Declarative Syntax"> for examples.
=cut
projects / chaz / p5-File-KDBX / commitdiff
