X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=lib%2FFile%2FKDBX.pm;h=5d188fb9793b628417bbbc586ceabf9a5c875235;hb=b334578b1eb03deabcdcc02f324e7d2323c7965e;hp=4151891f1197de86fa4a42b4a1a609bd47e93e5c;hpb=808d6cac614e8cd1ecb4f62570f49171e5169fa4;p=chaz%2Fp5-File-KDBX diff --git a/lib/File/KDBX.pm b/lib/File/KDBX.pm index 4151891..5d188fb 100644 --- a/lib/File/KDBX.pm +++ b/lib/File/KDBX.pm @@ -1,6 +1,7 @@ package File::KDBX; # ABSTRACT: Encrypted database to store secret text and files +use 5.010; use warnings; use strict; @@ -341,7 +342,7 @@ might increase this value. For example, setting the KDF to Argon2 will increase least C (i.e. C<0x00040000>) because Argon2 was introduced with KDBX4. This method never returns less than C (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 If you dump a database with a minimum version higher than the current L, the dumper will typically issue a warning and automatically upgrade the database. This seems like the safest behavior in order @@ -636,7 +637,7 @@ sub groups { my %args = @_ % 2 == 0 ? @_ : (base => shift, @_); my $base = delete $args{base} // $self->root; - return $base->groups_deeply(%args); + return $base->all_groups(%args); } ############################################################################## @@ -694,7 +695,7 @@ sub entries { my %args = @_ % 2 == 0 ? @_ : (base => shift, @_); my $base = delete $args{base} // $self->root; - return $base->entries_deeply(%args); + return $base->all_entries(%args); } ############################################################################## @@ -715,7 +716,7 @@ sub objects { 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 } @@ -1155,11 +1156,11 @@ our %PLACEHOLDERS = ( $kdbx->lock; -Encrypt all protected binaries strings in a database. The encrypted strings are stored in -a L associated with the database and the actual strings will be replaced with C to +Encrypt all protected strings and binaries in a database. The encrypted data is stored in +a L associated with the database and the actual values will be replaced with C to indicate their protected state. Returns itself to allow method chaining. -You can call C on an already-locked database to memory-protect any unprotected strings and binaries +You can call C on an already-locked database to memory-protect any unprotected strings and binaries added after the last time the database was locked. =cut @@ -1192,8 +1193,8 @@ sub lock { $kdbx->unlock; -Decrypt all protected strings in a database, replacing C placeholders with unprotected values. Returns -itself to allow method chaining. +Decrypt all protected strings and binaries in a database, replacing C value placeholders with their +actual, unprotected values. Returns itself to allow method chaining. =cut @@ -1216,6 +1217,14 @@ C if the database is already unlocked. See L and L. +Example: + + { + my $guard = $kdbx->unlock_scoped; + ...; + } + # $kdbx is now memory-locked + =cut sub unlock_scoped { @@ -1249,13 +1258,13 @@ sub 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 C values) until L 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 values) until L is called. =cut -sub is_locked { $_[0]->_safe ? 1 : 0 } +sub is_locked { !!$_[0]->_safe } ############################################################################## @@ -1419,8 +1428,8 @@ sub randomize_seeds { $key = $kdbx->key($primitive); Get or set a L. 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 B. See L for an -explanation of what the primitive can be. +a database). You can also pass a primitive castable to a B. See L 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. @@ -1708,7 +1717,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. -See L. +See L. =attr compression_flags @@ -1813,7 +1822,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. -C does NOT enforce it. +B does NOT enforce it. =attr custom_icons @@ -1900,22 +1909,27 @@ __END__ 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', ); + # Save the database to the filesystem $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!'); - $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', 'M@st3rP@ssw0rd!'); - $kdbx->entries->each(sub { + # Iterate over database entries, print entry titles + $kdbx2->entries->each(sub { my ($entry) = @_; say 'Entry: ', $entry->title; }); @@ -2372,7 +2386,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, L and L. You can specify the search algorithm to iterate over objects in different orders -using the C option, which can be one of these L: +using the C option, which can be one of these L: =for :list * C - Iterative deepening search (default) @@ -2411,12 +2425,12 @@ B - This is a planned feature, not yet implemented. =head1 ERRORS Errors in this package are constructed as L objects and propagated using perl's built-in -mechanisms. Fatal errors are propagated using L and non-fatal errors (a.k.a. warnings) are -propagated using L while adhering to perl's L system. If you're already familiar -with these mechanisms, you can skip this section. +mechanisms. Fatal errors are propagated using L and non-fatal errors (a.k.a. warnings) +are propagated using L while adhering to perl's L system. If you're already +familiar with these mechanisms, you can skip this section. -You can catch fatal errors using L (or something like L) and non-fatal errors using -C<$SIG{__WARN__}> (see L). Examples: +You can catch fatal errors using L (or something like L) and non-fatal +errors using C<$SIG{__WARN__}> (see L). Examples: use File::KDBX::Error qw(error); @@ -2477,13 +2491,6 @@ This software will alter its behavior depending on the value of certain environm * C - Do not use L if true (default: false) * C - 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, 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