From 2e2a003e118803b164b17bed666c10c829480564 Mon Sep 17 00:00:00 2001 From: Charles McGarvey Date: Sat, 30 Apr 2022 19:29:00 -0600 Subject: [PATCH] List features in documentation and fix some typos --- lib/File/KDBX.pm | 65 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/lib/File/KDBX.pm b/lib/File/KDBX.pm index 12e87f3..e7d11b3 100644 --- a/lib/File/KDBX.pm +++ b/lib/File/KDBX.pm @@ -1912,16 +1912,18 @@ __END__ $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!'); - kdbx->entries->each(sub { + $kdbx->entries->each(sub { my ($entry) = @_; say 'Entry: ', $entry->title; }); +See L for more examples. + =head1 DESCRIPTION B provides everything you need to work with a KDBX database. 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 for more information about KDBX. +password safe. See L 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. @@ -1932,12 +1934,35 @@ that works well in most cases but has a small backlog of bugs and security issue newer KDBX version 4 files. If you're coming here from the B world, you might be interested in L that is a drop-in replacement for B that uses B for storage. -=head2 KDBX Introduction +This software is a B. The interface should be considered pretty stable, but there might be +minor changes up until a 1.0 release. Breaking changes will be noted in the F file. + +=head2 Features -A KDBX database consists of a hierarchical I of I. Entries can contain zero or more key-value -pairs of I and zero or more I (i.e. octet strings). Groups, entries, strings and binaries: -that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is associated with each entry, group -and the database as a whole. +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) +* ☑ Unicode character strings +* ☑ L Searching +* ☑ L and L +* ☑ L +* ☑ L +* ☑ L +* ☑ Challenge-response key components, like L +* ☑ Variety of L types: binary, hexed, hashed, XML v1 and v2 +* ☑ Pluggable registration of different kinds of ciphers and key derivation functions +* ☑ Built-in database maintenance functions +* ☑ Pretty fast, with L available +* ☒ Database synchronization / merging (not yet) + +=head2 Introduction to KDBX + +A KDBX database consists of a tree of I and I, with a single I group. Entries can +contain zero or more key-value pairs of I and zero or more I (i.e. octet strings). Groups, +entries, strings and binaries: that's the KDBX vernacular. A small amount of metadata (timestamps, etc.) is +associated with each entry, group and the database as a whole. 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. @@ -1946,8 +1971,9 @@ Databases are typically persisted as a encrypted, compressed files. They are usu 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. Even if the database file were to be "leaked" to the public Internet, it -should be virtually impossible to crack with a strong key. See L for an overview of security -considerations. +should be virtually impossible to crack with a strong key. The KDBX format is most often used by password +managers to store passwords so that users can know a single strong password and not have to reuse passwords +across different websites. See L for an overview of security considerations. =head1 RECIPES @@ -2344,16 +2370,16 @@ your own query logic, like this: =head2 Iteration 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: +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: =for :list -* C - Iterative deepending search (default) +* C - Iterative deepening search (default) * C - Depth-first search -* C - Breatdth-first search +* C - Breadth-first search -When iterating over objects generically, groups always preceed their direct entries (if any). When the -C option is used, current entries always preceed historical entries. +When iterating over objects generically, groups always precede their direct entries (if any). When the +C option is used, current entries always precede historical entries. If you have a database tree like this: @@ -2378,7 +2404,7 @@ 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 MERGING +=head1 SYNCHRONIZING B - This is a planned feature, not yet implemented. @@ -2460,7 +2486,10 @@ when trying to use such features with undersized IVs. =head1 SEE ALSO -L is a much older alternative. It's good but has a backlog of bugs and lacks support for newer -KDBX features. +=for :list +* L - The original KeePass +* L - Cross-Platform Password Manager written in C++ +* L has overlapping functionality. It's good but has a backlog of some pretty critical bugs and + lacks support for newer KDBX features. =cut -- 2.43.0