Provided by: libfile-kdbx-perl_0.906-2_all bug

NAME

       File::KDBX - Encrypted database to store secret text and files

VERSION

       version 0.906

SYNOPSIS

           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', 'masterpw changeme');

           # Load the database from the filesystem into a new database instance
           my $kdbx2 = File::KDBX->load_file('passwords.kdbx', 'masterpw changeme');

           # Iterate over database entries, print entry titles
           $kdbx2->entries->each(sub($entry, @) {
               say 'Entry: ', $entry->title;
           });

       See "RECIPES" for more examples.

DESCRIPTION

       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 "Introduction to KDBX" for more information about KDBX.

       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 KeePassXC <https://github.com/keepassxreboot/keepassxc>
       implementation of KeePass as well as the File::KeePass module. 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 File::KeePass world, you might be
       interested in File::KeePass::KDBX that is a drop-in replacement for File::KeePass that uses File::KDBX
       for storage.

       This software is a pre-1.0 release. 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 Changes file.

   Features
       •   ☑ Read and write KDBX version 3 - version 4.1

       •   ☑ Read and write KDB files (requires File::KeePass)

       •   ☑ Unicode character strings

       •   ☑ "Simple Expression" Searching

       •   ☑ Placeholders and field references

       •   ☑ One-time passwords

       •   ☑ Very secure

       •   ☑ "Memory Protection"

       •   ☑ Challenge-response key components, like YubiKey

       •   ☑ Variety of key file 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 XS optimizations available

       •   ☒ Database synchronization / merging (not yet)

   Introduction to KDBX
       A  KDBX  database consists of a tree of groups and entries, with a single root group. Entries can contain
       zero or more key-value pairs of strings and zero or more binaries (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.

       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 master key. Even if the database file were to be "leaked" to  the  public
       Internet,  it  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 "SECURITY" for an overview of security considerations.

ATTRIBUTES

   sig1
   sig2
   version
   headers
   inner_headers
   meta
   binaries
   deleted_objects
       Hash of UUIDs for objects that have been deleted. This includes groups, entries and even custom icons.

   raw
       Bytes  contained  within  the  encrypted  layer  of  a  KDBX  file.  This  is   only   set   when   using
       File::KDBX::Loader::Raw.

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

   compression_flags
       Configuration  for  whether  or  not  and  how  the  database  gets  compressed.  See  ":compression"  in
       File::KDBX::Constants.

   master_seed
       The master seed is a string of 32 random bytes that is used as  salt  in  hashing  the  master  key  when
       loading  and  saving the database. If a challenge-response key is used in the master key, the master seed
       is also the challenge.

       The master seed should be changed each time the database is saved to file.

   transform_seed
       The transform seed is a string of 32 random bytes that is used in the key derivation function, either  as
       the salt or the key (depending on the algorithm).

       The transform seed should be changed each time the database is saved to file.

   transform_rounds
       The  number  of  rounds  or  iterations used in the key derivation function. Increasing this number makes
       loading and saving the database slower in order to make dictionary and brute force attacks more costly.

   encryption_iv
       The initialization vector used by the cipher.

       The encryption IV should be changed each time the database is saved to file.

   inner_random_stream_key
       The encryption key (possibly including the IV, depending on the cipher) used  to  encrypt  the  protected
       strings within the database.

   stream_start_bytes
       A  string  of  32 random bytes written in the header and encrypted in the body. If the bytes do not match
       when loading a file then the wrong master key was used or the file is corrupt. Only KDBX  2  and  KDBX  3
       files  use  this. KDBX 4 files use an improved HMAC method to verify the master key and data integrity of
       the header and entire file body.

   inner_random_stream_id
       A number indicating the cipher algorithm used to encrypt  the  protected  strings  within  the  database,
       usually Salsa20 or ChaCha20. See ":random_stream" in File::KDBX::Constants.

   kdf_parameters
       A  hash/dict  of key-value pairs used to configure the key derivation function. This is the KDBX4+ way to
       configure the KDF, superceding "transform_seed" and "transform_rounds".

   generator
       The name of the software used to generate the KDBX file.

   header_hash
       The header hash used to verify that the file header is not corrupt. (KDBX 2 - KDBX 3.1, removed KDBX 4.0)

   database_name
       Name of the database.

   database_name_changed
       Timestamp indicating when the database name was last changed.

   database_description
       Description of the database

   database_description_changed
       Timestamp indicating when the database description was last changed.

   default_username
       When a new entry is created, the UserName string will be populated with this value.

   default_username_changed
       Timestamp indicating when the default username was last changed.

   color
       A color associated with the database (in the form "#ffffff" where  "f"  is  a  hexidecimal  digit).  Some
       agents use this to help users visually distinguish between different databases.

   master_key_changed
       Timestamp indicating when the master key was last changed.

   master_key_change_rec
       Number of days until the agent should prompt to recommend changing the master key.

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

   custom_icons
       Array of custom icons that can be associated with groups and entries.

       This list can be managed with the methods "add_custom_icon" and "remove_custom_icon".

   recycle_bin_enabled
       Boolean indicating whether removed groups and entries should go  to  a  recycle  bin  or  be  immediately
       deleted.

   recycle_bin_uuid
       The UUID of a group used to store thrown-away groups and entries.

   recycle_bin_changed
       Timestamp indicating when the recycle bin group was last changed.

   entry_templates_group
       The UUID of a group containing template entries used when creating new entries.

   entry_templates_group_changed
       Timestamp indicating when the entry templates group was last changed.

   last_selected_group
       The UUID of the previously-selected group.

   last_top_visible_group
       The UUID of the group visible at the top of the list.

   history_max_items
       The maximum number of historical entries that should be kept for each entry. Default is 10.

   history_max_size
       The  maximum  total size (in bytes) that each individual entry's history is allowed to grow. Default is 6
       MiB.

   maintenance_history_days
       The maximum age (in days) historical entries should be kept. Default it 365.

   settings_changed
       Timestamp indicating when the database settings were last updated.

   protect_title
       Alias of the "memory_protection" setting for the Title string.

   protect_username
       Alias of the "memory_protection" setting for the UserName string.

   protect_password
       Alias of the "memory_protection" setting for the Password string.

   protect_url
       Alias of the "memory_protection" setting for the URL string.

   protect_notes
       Alias of the "memory_protection" setting for the Notes string.

METHODS

   new
           $kdbx = File::KDBX->new(%attributes);
           $kdbx = File::KDBX->new($kdbx); # copy constructor

       Construct a new File::KDBX.

   init
           $kdbx = $kdbx->init(%attributes);

       Initialize a File::KDBX with a set of attributes. Returns itself to allow method chaining.

       This is called by "new".

   reset
           $kdbx = $kdbx->reset;

       Set a File::KDBX to an empty state, ready to load a KDBX file or build a new one. Returns itself to allow
       method chaining.

   clone
           $kdbx_copy = $kdbx->clone;
           $kdbx_copy = File::KDBX->new($kdbx);

       Clone a File::KDBX. The clone will be an exact copy and completely independent of the original.

   load
   load_string
   load_file
   load_handle
           $kdbx = KDBX::File->load(\$string, $key);
           $kdbx = KDBX::File->load(*IO, $key);
           $kdbx = KDBX::File->load($filepath, $key);
           $kdbx->load(...);           # also instance method

           $kdbx = File::KDBX->load_string($string, $key);
           $kdbx = File::KDBX->load_string(\$string, $key);
           $kdbx->load_string(...);    # also instance method

           $kdbx = File::KDBX->load_file($filepath, $key);
           $kdbx->load_file(...);      # also instance method

           $kdbx = File::KDBX->load_handle($fh, $key);
           $kdbx = File::KDBX->load_handle(*IO, $key);
           $kdbx->load_handle(...);    # also instance method

       Load a KDBX file from a string buffer, IO handle or file from a filesystem.

       File::KDBX::Loader does the heavy lifting.

   dump
   dump_string
   dump_file
   dump_handle
           $kdbx->dump(\$string, $key);
           $kdbx->dump(*IO, $key);
           $kdbx->dump($filepath, $key);

           $kdbx->dump_string(\$string, $key);
           \$string = $kdbx->dump_string($key);

           $kdbx->dump_file($filepath, $key);

           $kdbx->dump_handle($fh, $key);
           $kdbx->dump_handle(*IO, $key);

       Dump a KDBX file to a string buffer, IO handle or file in a filesystem.

       File::KDBX::Dumper does the heavy lifting.

   user_agent_string
           $string = $kdbx->user_agent_string;

       Get a text string identifying the database client software.

   memory_protection
           \%settings = $kdbx->memory_protection
           $kdbx->memory_protection(\%settings);

           $bool = $kdbx->memory_protection($string_key);
           $kdbx->memory_protection($string_key => $bool);

       Get or set memory protection settings. This globally (for the  whole  database)  configures  whether  and
       which  of  the standard strings should be memory-protected. The default setting is to memory-protect only
       Password strings.

       Memory protection can be toggled individually  for  each  entry  string,  and  individual  settings  take
       precedence over these global settings.

   minimum_version
           $version = $kdbx->minimum_version;

       Determine  the  minimum  file  version  required  to  save a database losslessly. Using certain databases
       features might increase this value. For example, setting the KDF to  Argon2  will  increase  the  minimum
       version to at 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
       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", the dumper will
       typically issue a warning and automatically upgrade the database. This seems like the safest behavior  in
       order  to avoid data loss, but lower versions have the benefit of being compatible with more software. It
       is possible to prevent auto-upgrades by explicitly telling the dumper which version to use,  but  you  do
       run the risk of data loss. A database will never be automatically downgraded.

   root
           $group = $kdbx->root;
           $kdbx->root($group);

       Get  or  set a database's root group. You don't necessarily need to explicitly create or set a root group
       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 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.

   trace_lineage
           \@lineage = $kdbx->trace_lineage($group);
           \@lineage = $kdbx->trace_lineage($group, $base_group);
           \@lineage = $kdbx->trace_lineage($entry);
           \@lineage = $kdbx->trace_lineage($entry, $base_group);

       Get the direct line of ancestors from $base_group (default: the root group) to  a  group  or  entry.  The
       lineage  includes  the base group but not the target group or entry. Returns "undef" if the target is not
       in the database structure.

   recycle_bin
           $group = $kdbx->recycle_bin;
           $kdbx->recycle_bin($group);

       Get or set the recycle bin group. Returns "undef" if there is no recycle bin and "recycle_bin_enabled" is
       false, otherwise the current recycle bin or an autovivified recycle bin group is returned.

   entry_templates
           $group = $kdbx->entry_templates;
           $kdbx->entry_templates($group);

       Get or set the entry templates group. May return "undef" if unset.

   last_selected
           $group = $kdbx->last_selected;
           $kdbx->last_selected($group);

       Get or set the last selected group. May return "undef" if unset.

   last_top_visible
           $group = $kdbx->last_top_visible;
           $kdbx->last_top_visible($group);

       Get or set the last top visible group. May return "undef" if unset.

   add_group
           $kdbx->add_group($group);
           $kdbx->add_group(%group_attributes, %options);

       Add a group to a database. This is equivalent to identifying a parent group and  calling  "add_group"  in
       File::KDBX::Group on the parent group, forwarding the arguments. Available options:

       •   "group" - Group object or group UUID to add the group to (default: root group)

   groups
           \&iterator = $kdbx->groups(%options);
           \&iterator = $kdbx->groups($base_group, %options);

       Get an File::KDBX::Iterator over groups within a database. Options:

       •   "base" - Only include groups within a base group (same as $base_group) (default: "root")

       •   "inclusive" - Include the base group in the results (default: true)

       •   "algorithm" - Search algorithm, one of "ids", "bfs" or "dfs" (default: "ids")

   add_entry
           $kdbx->add_entry($entry, %options);
           $kdbx->add_entry(%entry_attributes, %options);

       Add  an  entry to a database. This is equivalent to identifying a parent group and calling "add_entry" in
       File::KDBX::Group on the parent group, forwarding the arguments. Available options:

       •   "group" - Group object or group UUID to add the entry to (default: root group)

   entries
           \&iterator = $kdbx->entries(%options);
           \&iterator = $kdbx->entries($base_group, %options);

       Get an File::KDBX::Iterator over entries within a database. Supports the same options as  "groups",  plus
       some new ones:

       •   "auto_type" - Only include entries with auto-type enabled (default: false, include all)

       •   "searching" - Only include entries within groups with searching enabled (default: false, include all)

       •   "history" - Also include historical entries (default: false, include only current entries)

   objects
           \&iterator = $kdbx->objects(%options);
           \&iterator = $kdbx->objects($base_group, %options);

       Get an File::KDBX::Iterator over objects within a database. Groups and entries are considered objects, so
       this  is  essentially  a combination of "groups" and "entries". This won't often be useful, but it can be
       convenient for maintenance tasks. This method takes the same options as "groups" and "entries".

   custom_icon
           \%icon = $kdbx->custom_icon($uuid);
           $kdbx->custom_icon($uuid => \%icon);
           $kdbx->custom_icon(%icon);
           $kdbx->custom_icon(uuid => $value, %icon);

       Get or set custom icons.

   custom_icon_data
           $image_data = $kdbx->custom_icon_data($uuid);

       Get a custom icon image data.

   add_custom_icon
           $uuid = $kdbx->add_custom_icon($image_data, %attributes);
           $uuid = $kdbx->add_custom_icon(%attributes);

       Add a custom icon and get its  UUID.  If  not  provided,  a  random  UUID  will  be  generated.  Possible
       attributes:

       •   "uuid" - Icon UUID (default: autogenerated)

       •   "data" - Image data (same as $image_data)

       •   "name" - Name of the icon (text, KDBX4.1+)

       •   "last_modification_time" - Just what it says (datetime, KDBX4.1+)

   remove_custom_icon
           $kdbx->remove_custom_icon($uuid);

       Remove a custom icon.

   custom_data
           \%all_data = $kdbx->custom_data;
           $kdbx->custom_data(\%all_data);

           \%data = $kdbx->custom_data($key);
           $kdbx->custom_data($key => \%data);
           $kdbx->custom_data(%data);
           $kdbx->custom_data(key => $value, %data);

       Get and set custom data. Custom data is metadata associated with a database.

       Each data item can have a few attributes associated with it.

       •   "key" - A unique text string identifier used to look up the data item (required)

       •   "value" - A text string value (required)

       •   "last_modification_time" (optional, KDBX4.1+)

   custom_data_value
           $value = $kdbx->custom_data_value($key);

       Exactly  the same as "custom_data" except returns just the custom data's value rather than a structure of
       attributes. This is a shortcut for:

           my $data = $kdbx->custom_data($key);
           my $value = defined $data ? $data->{value} : undef;

   public_custom_data
           \%all_data = $kdbx->public_custom_data;
           $kdbx->public_custom_data(\%all_data);

           $value = $kdbx->public_custom_data($key);
           $kdbx->public_custom_data($key => $value);

       Get and set public custom data. Public custom data is similar  to  custom  data  but  different  in  some
       important ways. Public custom data:

       •   can store strings, booleans and up to 64-bit integer values (custom data can only store text values)

       •   is NOT encrypted within a KDBX file (hence the "public" part of the name)

       •   is a plain hash/dict of key-value pairs with no other associated fields (like modification times)

   add_deleted_object
           $kdbx->add_deleted_object($uuid);

       Add a UUID to the deleted objects list. This list is used to support automatic database merging.

       You  typically  do  not  need  to  call this yourself because the list will be populated automatically as
       objects are removed.

   remove_deleted_object
           $kdbx->remove_deleted_object($uuid);

       Remove a UUID from the deleted objects list. This list is used to support automatic database merging.

       You typically do not need to call this yourself because the list  will  be  maintained  automatically  as
       objects are added.

   clear_deleted_objects
       Remove all UUIDs from the deleted objects list.  This list is used to support automatic database merging,
       but if you don't need merging then you can clear deleted objects to reduce the database file size.

   resolve_reference
           $string = $kdbx->resolve_reference($reference);
           $string = $kdbx->resolve_reference($wanted, $search_in, $expression);

       Resolve a field reference <https://keepass.info/help/base/fieldrefs.html>. A field reference is a kind of
       string  placeholder. You can use a field reference to refer directly to a standard field within an entry.
       Field references are resolved automatically while expanding entry strings (i.e. replacing  placeholders),
       but you can use this method to resolve on-the-fly references that aren't part of any actual string in the
       database.

       If  the  reference  does  not  resolve  to  any  field, "undef" is returned. If the reference resolves to
       multiple fields, only the first one is returned (in the same order as iterated by  "entries").  To  avoid
       ambiguity, you can refer to a specific entry by its UUID.

       The  syntax  of a reference is: "{REF:<WantedField>@<SearchIn>:<Text>}". "Text" is a "Simple Expression".
       "WantedField" and "SearchIn" are both single character codes representing a field:

       •   "T" - Title

       •   "U" - UserName

       •   "P" - Password

       •   "A" - URL

       •   "N" - Notes

       •   "I" - UUID

       •   "O" - Other custom strings

       Since "O" does not represent any specific field, it cannot be used as the "WantedField".

       Examples:

       To get the value of the UserName string of the first entry with "My Bank" in the title:

           my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
           # OR the {REF:...} wrapper is optional
           my $username = $kdbx->resolve_reference('U@T:"My Bank"');
           # OR separate the arguments
           my $username = $kdbx->resolve_reference(U => T => '"My Bank"');

       Note how the text is a "Simple Expression", so search terms with spaces  must  be  surrounded  in  double
       quotes.

       To get the Password string of a specific entry (identified by its UUID):

           my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');

   lock
           $kdbx->lock;

       Encrypt  all  protected  strings  and  binaries  in  a  database.  The  encrypted  data  is  stored  in a
       File::KDBX::Safe 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 "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 and binaries in a database, replacing "undef" value placeholders with their
       actual, unprotected values. Returns itself to allow method chaining.

   unlock_scoped
           $guard = $kdbx->unlock_scoped;

       Unlock a database temporarily, relocking when the guard is released (typically at the end  of  a  scope).
       Returns "undef" if the database is already unlocked.

       See "lock" and "unlock".

       Example:

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

   peek
           $string = $kdbx->peek(\%string);
           $string = $kdbx->peek(\%binary);

       Peek  at the value of a protected string or binary without unlocking the whole database. The argument can
       be  a  string  or  binary  hashref  as  returned  by  "string"  in  File::KDBX::Entry  or   "binary"   in
       File::KDBX::Entry.

   is_locked
           $bool = $kdbx->is_locked;

       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" is called.

   remove_empty_groups
           $kdbx->remove_empty_groups;

       Remove groups with no subgroups and no entries.

   remove_unused_icons
           $kdbx->remove_unused_icons;

       Remove icons that are not associated with any entry or group in the database.

   remove_duplicate_icons
           $kdbx->remove_duplicate_icons;

       Remove duplicate icons as determined by hashing the icon data.

   prune_history
           $kdbx->prune_history(%options);

       Remove just as many older historical entries as necessary to get under certain limits.

       •   "max_items" - Maximum number of historical entries to keep (default: value of "history_max_items", no
           limit: -1)

       •   "max_size" - Maximum total size  (in  bytes)  of  historical  entries  to  keep  (default:  value  of
           "history_max_size", no limit: -1)

       •   "max_age"   -   Maximum   age   (in   days)   of  historical  entries  to  keep  (default:  value  of
           "maintenance_history_days", no limit: -1)

   randomize_seeds
           $kdbx->randomize_seeds;

       Set various keys, seeds and IVs to random values. These values are used by  the  cryptographic  functions
       that secure the database when dumped. The attributes that will be randomized are:

       •   "encryption_iv"

       •   "inner_random_stream_key"

       •   "master_seed"

       •   "stream_start_bytes"

       •   "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  for  you  by
       default.

   key
           $key = $kdbx->key;
           $key = $kdbx->key($key);
           $key = $kdbx->key($primitive);

       Get  or  set  a File::KDBX::Key. This is the master key (e.g. a password or a key file that can decrypt a
       database). You can also pass a primitive  castable  to  a  Key.  See  "new"  in  File::KDBX::Key  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.

   composite_key
           $key = $kdbx->composite_key($key);
           $key = $kdbx->composite_key($primitive);

       Construct a File::KDBX::Key::Composite from a Key or primitive.  See  "new"  in  File::KDBX::Key  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 loader and dumper use it to transform a master key
       into a raw encryption key.

   kdf
           $kdf = $kdbx->kdf(%options);
           $kdf = $kdbx->kdf(\%parameters, %options);

       Get a File::KDBX::KDF (key derivation function).

       Options:

       •   "params" - KDF parameters, same as "\%parameters" (default: value of "kdf_parameters")

   cipher
           $cipher = $kdbx->cipher(key => $key);
           $cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);

       Get a File::KDBX::Cipher capable of encrypting and decrypting the body of a database file.

       A key is required. This should be a raw encryption key made up of a fixed number of octets (depending  on
       the cipher), not a File::KDBX::Key or primitive.

       If  not  passed,  the  UUID  comes  from  "$kdbx->headers->{cipher_id}"  and the encryption IV comes from
       "$kdbx->headers->{encryption_iv}".

       You generally don't need to call this directly. The loader and dumper use it to decrypt and encrypt  KDBX
       files.

   random_stream
           $cipher = $kdbx->random_stream;
           $cipher = $kdbx->random_stream(id => $stream_id, key => $key);

       Get a File::KDBX::Cipher::Stream for decrypting and encrypting protected values.

       If  not  passed,  the  ID  and  encryption  key comes from "$kdbx->headers->{inner_random_stream_id}" and
       "$kdbx->headers->{inner_random_stream_key}"    (respectively)    for     KDBX3     files     and     from
       "$kdbx->inner_headers->{inner_random_stream_key}"   and  "$kdbx->inner_headers->{inner_random_stream_id}"
       (respectively) for KDBX4 files.

       You generally don't need to call this directly. The loader  and  dumper  use  it  to  scramble  protected
       strings.

RECIPES

   Create a new database
           my $kdbx = File::KDBX->new;

           my $group = $kdbx->add_group(name => 'Passwords);
           my $entry = $group->add_entry(
               title    => 'WayneCorp',
               username => 'bwayne',
               password => 'iambatman',
               url      => 'https://example.com/login'
           );
           $entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');

           $kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');

   Read an existing database
           my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
           $kdbx->unlock;  # cause $entry->password below to be defined

           $kdbx->entries->each(sub($entry, @) {
               say 'Found password for: ', $entry->title;
               say '  Username: ', $entry->username;
               say '  Password: ', $entry->password;
           });

   Search for entries
           my @entries = $kdbx->entries(searching => 1)
               ->grep(title => 'WayneCorp')
               ->each;     # return all matches

       The "searching" option limits results to only entries within groups with searching enabled. Other options
       are also available. See "entries".

       See "QUERY" for many more query examples.

   Search for entries by auto-type window association
           my $window_title = 'WayneCorp - Mozilla Firefox';

           my $entries = $kdbx->entries(auto_type => 1)
               ->filter(sub {
                   my ($ata) = grep { $_->{window} =~ /\Q$window_title\E/i } @{$_->auto_type_associations};
                   return [$_, $ata->{keystroke_sequence}] if $ata;
               })
               ->each(sub {
                   my ($entry, $keys) = @$_;
                   say 'Entry title: ', $entry->title, ', key sequence: ', $keys;
               });

       Example output:

           Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}

   Remove entries from a database
           $kdbx->entries
               ->grep(notes => {'=~' => qr/too old/i})
               ->each(sub { $_->recycle });

       Recycle all entries with the string "too old" appearing in the Notes string.

   Remove empty groups
           $kdbx->groups(algorithm => 'dfs')
               ->where(-true => 'is_empty')
               ->each('remove');

       With  the  search/iteration  "algorithm"  set to "dfs", groups will be ordered deepest first and the root
       group will be last. This allows removing groups that only contain empty groups.

       This can also be done with one call to "remove_empty_groups".

SECURITY

       One of the biggest threats to your database security is how easily  the  encryption  key  can  be  brute-
       forced.  Strong brute-force protection depends on:

       •   Using unguessable passwords, passphrases and key files.

       •   Using a brute-force resistent key derivation function.

       The  first  factor is up to you. This module does not enforce strong master keys. It is up to you to pick
       or generate strong keys.

       The KDBX format allows for the key derivation function to be tuned. The idea is that you want each single
       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.

       This    and    other    KDBX-related    security    issues    are    covered    here   more   in   depth:
       <https://keepass.info/help/base/security.html>

       Here are other security risks you should be thinking about:

   Cryptography
       This distribution uses the excellent CryptX and  Crypt::Argon2  packages  to  handle  all  crypto-related
       functions. As such, a lot of the security depends on the quality of these dependencies. Fortunately these
       modules are maintained and appear to have good track records.

       The  KDBX  format  has  evolved  over  time  to incorporate improved security practices and cryptographic
       functions.  This package uses the following functions for authentication, hashing, encryption and  random
       number generation:

       •   AES-128 (legacy)

       •   AES-256

       •   Argon2d & Argon2id

       •   CBC block mode

       •   HMAC-SHA256

       •   SHA256

       •   SHA512

       •   Salsa20 & ChaCha20

       •   Twofish

       At  the  time  of  this writing, I am not aware of any successful attacks against any of these functions.
       These are among the most-analyzed and widely-adopted crypto functions available.

       The KDBX format allows the body cipher and key derivation  function  to  be  configured.  If  a  flaw  is
       discovered  in one of these functions, you can hopefully just switch to a better function without needing
       to update this software. A later software release may phase out the use of any  functions  which  are  no
       longer secure.

   Memory Protection
       It  is not a good idea to keep secret information unencrypted in system memory for longer than is needed.
       The address space of your program can generally be read by a user with elevated privileges on the system.
       If your system is memory-constrained or goes into a hibernation mode, the contents of your address  space
       could be written to a disk where it might be persisted for long time.

       There  might  be  system-level  things  you  can  do  to reduce your risk, like using swap encryption and
       limiting system access to your program's address space while your program is running.

       File::KDBX helps minimize (but not eliminate) risk by keeping secrets encrypted in memory until  accessed
       and zeroing out memory that holds secrets after they're no longer needed, but it's not a silver bullet.

       For  one thing, the encryption key is stored in the same address space. If core is dumped, the encryption
       key is available to be found out. But at least there is the  chance  that  the  encryption  key  and  the
       encrypted secrets won't both be paged out together while memory-constrained.

       Another  problem  is  that  some  perls (somewhat notoriously) copy around memory behind the scenes willy
       nilly, and it's difficult know when perl makes a copy of a secret in order to be  able  to  zero  it  out
       later.  It  might  be impossible. The good news is that perls with SvPV copy-on-write (enabled by default
       beginning with perl 5.20) are much better in this regard. With COW, it's mostly  possible  to  know  what
       operations  will  cause  perl  to  copy  the  memory of a scalar string, and the number of copies will be
       significantly reduced. There is a unit test named t/memory-protection.t in this distribution that can  be
       run on POSIX systems to determine how well File::KDBX memory protection is working.

       Memory  protection  also  depends  on  how your application handles secrets. If your app code is handling
       scalar strings with secret information, it's up to you to make sure its memory  is  zeroed  out  when  no
       longer  needed.   "erase"  in  File::KDBX::Util  et al. provide some tools to help accomplish this. Or if
       you're not too concerned about the risks memory protection is meant to mitigate, then maybe  don't  worry
       about  it.  The security policy of File::KDBX is to try hard to keep secrets protected while in memory so
       that your app might claim a high level of security, in case you care about that.

       There are some memory protection strategies that File::KDBX does NOT use today but could in the future:

       Many systems allow programs to mark unswappable pages. Secret information should  ideally  be  stored  in
       such pages. You could potentially use mlockall(2) (or equivalent for your system) in your own application
       to prevent the entire address space from being swapped.

       Some  systems  provide  special  syscalls  for storing secrets in memory while keeping the encryption key
       outside of the program's address space, like "CryptProtectMemory" for  Windows.  This  could  be  a  good
       option, though unfortunately not portable.

QUERY

       To  find  things in a KDBX database, you should use a filtered iterator. If you have an iterator, such as
       returned  by  "entries",  "groups"  or  even   "objects"   you   can   filter   it   using   "where"   in
       File::KDBX::Iterator.

           my $filtered_entries = $kdbx->entries->where(\&query);

       A "\&query" is just a subroutine that you can either write yourself or have generated for you from either
       a  "Simple  Expression"  or "Declarative Syntax". It's easier to have your query generated, so I'll cover
       that first.

   Simple Expression
       A  simple  expression  is  mostly  compatible  with  the  KeePass   2   implementation   described   here
       <https://keepass.info/help/base/search.html#mode_se>.

       An  expression  is  a string with one or more space-separated terms. Terms with spaces can be enclosed in
       double quotes. Terms are negated if they are prefixed with a minus sign. A record must match  every  term
       on at least one of the given fields.

       So  a  simple  expression  is something like what you might type into a search engine. You can generate a
       simple expression query using "simple_expression_query" in File::KDBX::Util  or  by  passing  the  simple
       expression as a scalar reference to "where".

       To search for all entries in a database with the word "canyon" appearing anywhere in the title:

           my $entries = $kdbx->entries->where(\'canyon', qw[title]);

       Notice  the  first  argument  is  a scalarref. This disambiguates a simple expression from other types of
       queries covered below.

       As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry
       that has the words "red" and "canyon" anywhere in the title:

           my $entries = $kdbx->entries->where(\'red canyon', qw[title]);

       Each term in the simple expression must be found for an entry to match.

       To search for entries with "red" in the title but not "canyon", just prepend "canyon" with a minus sign:

           my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);

       To search over multiple fields simultaneously, just list them all. To search for entries  with  "grocery"
       (but not "Foodland") in the title or notes:

           my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);

       The  default  operator  is a case-insensitive regexp match, which is fine for searching text loosely. You
       can use just about any binary comparison operator that perl supports. To specify  an  operator,  list  it
       after the simple expression. For example, to search for any entry that has been used at least five times:

           my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);

       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 use the
       "simple_expression_query" in File::KDBX::Util function as a more  intuitive  alternative.  The  following
       example is equivalent to the previous:

           my $entries = $kdbx->entries->where(simple_expression_query(5, '>=', qw[usage_count]));

   Declarative Syntax
       Structuring  a declarative query is similar to "WHERE CLAUSES" in SQL::Abstract, but you don't have to be
       familiar with that module. Just learn by examples here.

       To search for all entries in a database titled "My Bank":

           my $entries = $kdbx->entries->where({ title => 'My Bank' });

       The query here is "{ title => 'My Bank' }". A hashref can contain key-value pairs where  the  key  is  an
       attribute  of  the  thing  being  searched for (in this case an entry) and the value is what you want the
       thing's attribute to be to consider it a match. In this case, the attribute  we're  using  as  our  match
       criteria  is "title" in File::KDBX::Entry, a text field. If an entry has its title attribute equal to "My
       Bank", it's a match.

       A hashref can contain multiple attributes. The search candidate will be a match if all of  the  specified
       attributes are equal to their respective values. For example, to search for all entries with a particular
       URL AND username:

           my $entries = $kdbx->entries->where({
               url      => 'https://example.com',
               username => 'neo',
           });

       To  search  for  entries  matching  any  criteria,  just change the hashref to an arrayref. To search for
       entries with a particular URL OR username:

           my $entries = $kdbx->entries->where([ # <-- Notice the square bracket
               url      => 'https://example.com',
               username => 'neo',
           ]);

       You can use different operators to test different types of attributes. The "icon_id" in File::KDBX::Entry
       attribute is a number, so we should  use  a  number  comparison  operator.  To  find  entries  using  the
       smartphone icon:

           my $entries = $kdbx->entries->where({
               icon_id => { '==', ICON_SMARTPHONE },
           });

       Note:  "ICON_SMARTPHONE" in File::KDBX::Constants is just a constant from File::KDBX::Constants. 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 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:

       •   "eq" - String equal

       •   "ne" - String not equal

       •   "lt" - String less than

       •   "gt" - String greater than

       •   "le" - String less than or equal

       •   "ge" - String greater than or equal

       •   "==" - Number equal

       •   "!=" - Number not equal

       •   "<" - Number less than

       •   ">" - Number greater than

       •   "<=" - Number less than or equal

       •   ">=" - Number less than or equal

       •   "=~" - String match regular expression

       •   "!~" - String does not match regular expression

       •   "!" - Boolean false

       •   "!!" - Boolean true

       Other special operators:

       •   "-true" - Boolean true

       •   "-false" - Boolean false

       •   "-not" - Boolean false (alias for "-false")

       •   "-defined" - Is defined

       •   "-undef" - Is not defined

       •   "-empty" - Is empty

       •   "-nonempty" - Is not empty

       •   "-or" - Logical or

       •   "-and" - Logical and

       Let's see another example using an explicit operator.  To  find  all  groups  except  one  in  particular
       (identified by its "uuid" in File::KDBX::Group), we can use the "ne" (string not equal) operator:

           my $groups = $kdbx->groups->where(
               uuid => {
                   'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
               },
           );

       Note:  "uuid"  in File::KDBX::Util is a little utility function to convert a UUID in its pretty form into
       bytes.  This utility function isn't special to this example or to queries generally. It could  have  been
       written with a literal such as "\x59\x6f\x75\x20\x61...", but that's harder to read.

       Notice we searched for groups this time. Finding groups works exactly the same as it does for entries.

       Notice  also  that  we didn't wrap the query in hashref curly-braces or arrayref square-braces. Those are
       optional. By default it will only match ALL attributes (as if there were curly-braces).

       Testing the truthiness of an attribute is a little bit different because it isn't a binary operation.  To
       find all entries with the password quality check disabled:

           my $entries = $kdbx->entries->where('!' => 'quality_check');

       This  time  the  string  after  the  operator  is  the  attribute name rather than a value to compare the
       attribute against. To test that a boolean value is true, use the "!!" operator (or "-true" if "!!"  seems
       a little too weird for your taste):

           my $entries = $kdbx->entries->where('!!'  => 'quality_check');
           my $entries = $kdbx->entries->where(-true => 'quality_check');  # same thing

       Yes,  there  is  also  a  "-false"  and a "-not" if you prefer one of those over "!". "-false" and "-not"
       (along with "-true") are also special in that you can use them to invert the logic of a  subquery.  These
       are logically equivalent:

           my $entries = $kdbx->entries->where(-not => { title => 'My Bank' });
           my $entries = $kdbx->entries->where(title => { 'ne' => 'My Bank' });

       These  special  operators  become  more  useful when combined with two more special operators: "-and" and
       "-or".  With these, it is possible to construct more  interesting  queries  with  groups  of  logic.  For
       example:

           my $entries = $kdbx->entries->where({
               title   => { '=~', qr/bank/ },
               -not    => {
                   -or     => {
                       notes   => { '=~', qr/business/ },
                       icon_id => { '==', ICON_TRASHCAN_FULL },
                   },
               },
           });

       In  English, find entries where the word "bank" appears anywhere in the title but also do not have either
       the word "business" in the notes or are using the full trashcan icon.

   Subroutine Query
       Lastly, as mentioned at the top, you can ignore all this and write your own subroutine.  Your  subroutine
       will  be  called  once  for  each  object  being searched over. The subroutine should match the candidate
       against whatever criteria you want and return true if it matches or false to skip. To do this, just  pass
       your subroutine coderef to "where".

       To  review  the  different types of queries, these are all equivalent to find all entries in the database
       titled "My Bank":

           my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]);     # simple expression
           my $entries = $kdbx->entries->where(title => 'My Bank');                # declarative syntax
           my $entries = $kdbx->entries->where(sub { $_->title eq 'My Bank' });    # subroutine query

       This is a trivial example, but of course your subroutine can be arbitrarily complex.

       All of these query mechanisms described in this section  are  just  tools,  each  with  its  own  set  of
       limitations.   If  the  tools  are  getting in your way, you can of course iterate over the contents of a
       database and implement your own query logic, like this:

           my $entries = $kdbx->entries;
           while (my $entry = $entries->next) {
               if (wanted($entry)) {
                   do_something($entry);
               }
               else {
                   ...
               }
           }

   Iteration
       Iterators are the built-in way to navigate or walk the database tree. You get an iterator from "entries",
       "groups" and "objects". You can specify the search algorithm to iterate over objects in different  orders
       using the "algorithm" option, which can be one of these constants:

       •   "ITERATION_IDS" - Iterative deepening search (default)

       •   "ITERATION_DFS" - Depth-first search

       •   "ITERATION_BFS" - Breadth-first search

       When  iterating  over  objects generically, groups always precede their direct entries (if any). When the
       "history" option is used, current entries always precede historical entries.

       If you have a database tree like this:

           Database
           - Root
               - Group1
                   - EntryA
                   - Group2
                       - EntryB
               - 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

SYNCHRONIZING

       TODO - This is a planned feature, not yet implemented.

ERRORS

       Errors in this package are constructed as File::KDBX::Error objects and propagated using perl's  built-in
       mechanisms.  Fatal  errors  are  propagated  using  "die  LIST"  in perlfunc and non-fatal errors (a.k.a.
       warnings) are propagated using "warn LIST" in perlfunc while  adhering  to  perl's  warnings  system.  If
       you're already familiar with these mechanisms, you can skip this section.

       You  can  catch  fatal  errors using "eval BLOCK" in perlfunc (or something like Try::Tiny) and non-fatal
       errors using $SIG{__WARN__} (see "%SIG" in perlvar). Examples:

           use File::KDBX::Error qw(error);

           my $key = '';   # uh oh
           eval {
               $kdbx->load_file('whatever.kdbx', $key);
           };
           if (my $error = error($@)) {
               handle_missing_key($error) if $error->type eq 'key.missing';
               $error->throw;
           }

       or using "Try::Tiny":

           try {
               $kdbx->load_file('whatever.kdbx', $key);
           }
           catch {
               handle_error($_);
           };

       Catching non-fatal errors:

           my @warnings;
           local $SIG{__WARN__} = sub { push @warnings, $_[0] };

           $kdbx->load_file('whatever.kdbx', $key);

           handle_warnings(@warnings) if @warnings;

       By default perl prints warnings to "STDERR" if you don't catch them. If you don't want to catch them  and
       also  don't  want  them  printed  to  "STDERR",  you  can  suppress  them lexically (perl v5.28 or higher
       required):

           {
               no warnings 'File::KDBX';
               ...
           }

       or locally:

           {
               local $File::KDBX::WARNINGS = 0;
               ...
           }

       or globally in your program:

           $File::KDBX::WARNINGS = 0;

       You cannot suppress fatal errors, and if you don't catch them your program will exit.

ENVIRONMENT

       This software will alter its behavior depending on the value of certain environment variables:

       •   "PERL_FILE_KDBX_XS" - Do not use File::KDBX::XS if false (default: true)

       •   "PERL_ONLY" - Do not use File::KDBX::XS if true (default: false)

       •   "NO_FORK" - Do not fork if true (default: false)

SEE ALSO

       •   KeePass Password Safe <https://keepass.info/> - The original KeePass

       •   KeePassXC <https://keepassxc.org/> - Cross-Platform Password Manager written in C++

       •   File::KeePass has overlapping functionality. It's good but has a backlog of some pretty critical bugs
           and lacks support for newer KDBX features.

BUGS

       Please    report    any    bugs     or     feature     requests     on     the     bugtracker     website
       <https://github.com/chazmcgarvey/File-KDBX/issues>

       When  submitting  a  bug  or request, please include a test-file or a patch to an existing test-file that
       illustrates the bug or desired feature.

AUTHOR

       Charles McGarvey <ccm@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2022 by Charles McGarvey.

       This is free software; you can redistribute it and/or modify it under  the  same  terms  as  the  Perl  5
       programming language system itself.

perl v5.36.0                                       2022-11-20                                    File::KDBX(3pm)