NAME

       File::KDBX::Key - A credential that can protect a KDBX file

VERSION

       version 0.906

DESCRIPTION

       A master key is one or more credentials that can protect a KDBX database. When you encrypt
       a database with a master key, you will need the master key to decrypt it. Keep your master
       key safe! If someone gains access to your master key, they can open your database. If you
       forget or lose any part of your master key, all data in the database is lost.

       There are several different types of keys, each implemented as a subclass:

       •   File::KDBX::Key::Password - Password or passphrase, knowledge of a string of
           characters

       •   File::KDBX::Key::File - Possession of a file ("key file") with a secret

       •   File::KDBX::Key::ChallengeResponse - Possession of a device that responds correctly
           when challenged

       •   File::KDBX::Key::YubiKey - Possession of a YubiKey hardware device (a type of
           challenge-response)

       •   File::KDBX::Key::Composite - One or more keys combined as one

       A good master key is produced from a high amount of "entropy" (unpredictability). The more
       entropy the better.  Combining multiple keys into a Composite key combines the entropy of
       each individual key. For example, if you have a weak password and you combine it with
       other keys, the composite key is stronger than the weak password key by itself. (Of course
       it's much better to not have any weak components of your master key.)

       COMPATIBILITY NOTE: Most KeePass implementations are limited in the types and numbers of
       keys they support.  Password keys are pretty much universally supported. File keys are
       pretty well-supported. Many do not support challenge-response keys. If you are concerned
       about compatibility, you should stick with one of these well-supported configurations:

       •   One password

       •   One key file

       •   Composite of one password and one key file

METHODS

   new
           $key = File::KDBX::Key->new({ password => $password });
           $key = File::KDBX::Key->new($password);

           $key = File::KDBX::Key->new({ file => $filepath });
           $key = File::KDBX::Key->new(\$file);
           $key = File::KDBX::Key->new(\*FILE);

           $key = File::KDBX::Key->new({ composite => [...] });
           $key = File::KDBX::Key->new([...]);         # composite key

           $key = File::KDBX::Key->new({ responder => \&responder });
           $key = File::KDBX::Key->new(\&responder);   # challenge-response key

       Construct a new key.

       The primitive used to construct the key is not saved but is immediately converted to a raw
       encryption key (see "raw_key").

       A File::KDBX::Key::Composite is somewhat special in that it does retain a reference to its
       component keys, and its raw key is calculated from its components on demand.

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

       Initialize a File::KDBX::Key with a new primitive. Returns itself to allow method
       chaining.

   reload
           $key = $key->reload;

       Reload a key by re-reading the key source and recalculating the raw key. Returns itself to
       allow method chaining.

   raw_key
           $raw_key = $key->raw_key;
           $raw_key = $key->raw_key($challenge);

       Get the raw encryption key. This is calculated based on the primitive(s). The $challenge
       argument is for challenge-response type keys and is ignored by other types.

       NOTE: The raw key is sensitive information and so is memory-protected while not being
       accessed. If you access it, you should memzero or "erase" in File::KDBX::Util it when
       you're done.

   hide
           $key = $key->hide;

       Put the raw key in memory protection. Does nothing if the raw key is already in memory
       protection. Returns itself to allow method chaining.

   show
           $key = $key->show;

       Bring the raw key out of memory protection. Does nothing if the raw key is already out of
       memory protection.  Returns itself to allow method chaining.

   is_hidden
           $bool = $key->is_hidden;

       Get whether or not the key's raw secret is currently in memory protection.

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.