Version 0.901

[chaz/p5-File-KDBX] / README

NAME

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

VERSION

    version 0.901

SYNOPSIS

        use File::KDBX;
    
        my $kdbx = File::KDBX->new;
    
        my $group = $kdbx->add_group(
            name => 'Passwords',
        );
    
        my $entry = $group->add_entry(
            title    => 'My Bank',
            password => 's3cr3t',
        );
    
        $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
    
        $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
    
        $kdbx->entries->each(sub {
            my ($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. 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 by
    design 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 ubiquitious 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 a 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: 365, 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 explicitly 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 {
            my ($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-foce 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 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 arrayref 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 algorith 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)

CAVEATS

    Some features (e.g. parsing) require 64-bit perl. It should be possible
    and actually pretty easy to make it work using Math::BigInt, 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.

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.