Prereq CryptX 0.049 for encode_b32*

[chaz/p5-File-KDBX] / lib / File / KDBX.pm

diff --git a/lib/File/KDBX.pm b/lib/File/KDBX.pm
index d3e501af1e8c562c781c82750a0e4f6bf5b1938a..fee9dc5ab854a7fce3d5376a1e9e09b1463c33de 100644 (file)
--- a/lib/File/KDBX.pm
+++ b/lib/File/KDBX.pm
@@ -264,7 +264,7 @@ has 'meta.database_description'             => '',                          coer
 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.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;
 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;


@@ -398,8 +398,9 @@ because it autovivifies when adding entries and groups to the database.
 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
 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.
 
 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.


@@ -592,7 +593,7 @@ Add a group to a database. This is equivalent to identifying a parent group and
 L<File::KDBX::Group/add_group> on the parent group, forwarding the arguments. Available options:
 
 =for :list
 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
 
 
 =cut
 


@@ -602,7 +603,7 @@ sub add_group {
     my %args    = @_;
 
     # find the right group to add the group to
     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';
 
     $parent = $self->groups->grep({uuid => $parent})->next if !ref $parent;
     $parent or throw 'Invalid group';
 


@@ -649,7 +650,7 @@ Add a entry to a database. This is equivalent to identifying a parent group and
 L<File::KDBX::Group/add_entry> on the parent group, forwarding the arguments. Available options:
 
 =for :list
 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
 
 
 =cut
 


@@ -659,7 +660,7 @@ sub add_entry {
     my %args    = @_;
 
     # find the right group to add the entry to
     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';
 
     $parent = $self->groups->grep({uuid => $parent})->next if !ref $parent;
     $parent or throw 'Invalid group';
 


@@ -1154,11 +1155,11 @@ our %PLACEHOLDERS = (
 
     $kdbx->lock;
 
 
     $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.
 
 indicate their protected state. Returns itself to allow method chaining.
 

-You can call C<code> on an already-locked database to memory-protect any unprotected strings and binaries
+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
 added after the last time the database was locked.
 
 =cut


@@ -1191,8 +1192,8 @@ sub lock {
 
     $kdbx->unlock;
 
 
     $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
 
 
 =cut
 


@@ -1215,6 +1216,14 @@ C<undef> if the database is already unlocked.
 
 See L</lock> and L</unlock>.
 
 
 See L</lock> and L</unlock>.
 

+Example:
+
+    {
+        my $guard = $kdbx->unlock_scoped;
+        ...;
+    }
+    # $kdbx is now memory-locked
+

 =cut
 
 sub unlock_scoped {
 =cut
 
 sub unlock_scoped {


@@ -1248,13 +1257,13 @@ sub peek {
 
     $bool = $kdbx->is_locked;
 
 
     $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
 
 
 =cut
 

-sub is_locked { $_[0]->_safe ? 1 : 0 }
+sub is_locked { !!$_[0]->_safe }

 
 ##############################################################################
 
 
 ##############################################################################
 


@@ -1368,7 +1377,7 @@ sub prune_history {
 
     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_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}   // HISTORY_DEFAULT_MAX_AGE;
+    my $max_age   = $args{max_age}   // $self->maintenance_history_days // HISTORY_DEFAULT_MAX_AGE;

 
     my @removed;
     $self->entries->each(sub {
 
     my @removed;
     $self->entries->each(sub {


@@ -1418,7 +1427,8 @@ sub 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
     $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.
 
 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.


@@ -1436,10 +1446,11 @@ sub key {
     $key = $kdbx->composite_key($key);
     $key = $kdbx->composite_key($primitive);
 
     $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
 a raw encryption key.
 
 =cut


@@ -1522,7 +1533,7 @@ cipher), not a L<File::KDBX::Key> or primitive.
 If not passed, the UUID comes from C<< $kdbx->headers->{cipher_id} >> and the encryption IV comes from
 C<< $kdbx->headers->{encryption_iv} >>.
 
 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
 files.
 
 =cut


@@ -1550,7 +1561,7 @@ C<< $kdbx->headers->{inner_random_stream_key} >> (respectively) for KDBX3 files
 C<< $kdbx->inner_headers->{inner_random_stream_key} >> and
 C<< $kdbx->inner_headers->{inner_random_stream_id} >> (respectively) for KDBX4 files.
 
 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
 
 
 =cut
 


@@ -1705,7 +1716,7 @@ A text string associated with the database. Often unset.
 
 The UUID of a cipher used to encrypt the database when stored as a file.
 
 
 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
 
 
 =attr compression_flags
 


@@ -1792,10 +1803,6 @@ When a new entry is created, the I<UserName> string will be populated with this
 
 Timestamp indicating when the default username was last changed.
 
 
 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
 =attr color
 
 A color associated with the database (in the form C<#ffffff> where "f" is a hexidecimal digit). Some agents


@@ -1814,7 +1821,7 @@ Number of days until the agent should prompt to recommend changing the master ke
 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.
 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
 
 
 =attr custom_icons
 


@@ -1832,7 +1839,7 @@ The UUID of a group used to store thrown-away groups and entries.
 
 =attr recycle_bin_changed
 
 
 =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 entry_templates_group
 


@@ -1852,11 +1859,15 @@ The UUID of the group visible at the top of the list.
 
 =attr history_max_items
 
 
 =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
 
 
 =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
 
 
 =attr settings_changed
 


@@ -1921,12 +1932,12 @@ See L</RECIPES> for more examples.
 
 =head1 DESCRIPTION
 
 
 =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</"Introduction to KDBX"> for more information about KDBX.
 
 object database which is commonly used to store secret information securely. It was developed for the KeePass
 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.

 
 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
 
 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


@@ -2148,9 +2159,9 @@ unfortunately not portable.
 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>.
 
 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_entries = $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.
 
 a L</"Simple Expression"> or L</"Declarative Syntax">. It's easier to have your query generated, so I'll cover
 that first.
 


@@ -2261,7 +2272,7 @@ operators are:
 * C<==> - Number equal
 * C<!=> - Number not equal
 * C<< < >> - Number less than
 * 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
 * C<< <= >> - Number less than or equal
 * C<< >= >> - Number less than or equal
 * C<=~> - String match regular expression


@@ -2369,7 +2380,7 @@ your own query logic, like this:
 
 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
 
 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)
 
 =for :list
 * C<ITERATION_IDS> - Iterative deepening search (default)


@@ -2408,12 +2419,12 @@ 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
 =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);
 
 
     use File::KDBX::Error qw(error);