NAME

       File::KDBX::KDF - A key derivation function

VERSION

       version 0.906

DESCRIPTION

       A KDF (key derivation function) is used in the transformation of a master key (i.e. one or more component
       keys) to produce the final encryption key protecting a KDBX database. The File::KDBX distribution comes
       with several pre-registered KDFs ready to go:

       •   "C9D9F39A-628A-4460-BF74-0D08C18A4FEA" - AES

       •   "7C02BB82-79A7-4AC0-927D-114A00648238" - AES (challenge-response variant)

       •   "EF636DDF-8C29-444B-91F7-A9A403E30A0C" - Argon2d

       •   "9E298B19-56DB-4773-B23D-FC3EC6F0A1E6" - Argon2id

       NOTE: If you want your KDBX file to be readable by other KeePass implementations, you must use a UUID and
       algorithm  that  they  support.  From  the  list  above, all are well-supported except the AES challenge-
       response variant which is kind of a pseudo KDF and isn't usually written into files.  All  of  these  are
       good. AES has a longer track record, but Argon2 has better ASIC resistance.

       You can also "register" your own KDF. Here is a skeleton:

           package File::KDBX::KDF::MyKDF;

           use parent 'File::KDBX::KDF';

           File::KDBX::KDF->register(
               # $uuid, $package, %args
               "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
           );

           sub init { ... } # optional

           sub _transform { my ($key) = @_; ... }

ATTRIBUTES

   uuid
           $uuid => $kdf->uuid;

       Get the UUID used to determine which function to use.

   seed
           $seed = $kdf->seed;

       Get the seed (or salt, depending on the function).

METHODS

   new
           $kdf = File::KDBX::KDF->new(parameters => \%params);

       Construct a new KDF.

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

       Called  by  "new"  to  set  attributes.  You normally shouldn't call this. Returns itself to allow method
       chaining.

   transform
           $transformed_key = $kdf->transform($key);
           $transformed_key = $kdf->transform($key, $challenge);

       Transform a key. The input key can be either a File::KDBX::Key or a raw binary key, and  the  transformed
       key will be a raw key.

       This can take awhile, depending on the KDF parameters.

       If  a  challenge  is provided (and the KDF is AES except for the KeePassXC variant), it will be passed to
       the key so challenge-response keys can produce raw keys. See "raw_key" in File::KDBX::Key.

   randomize_seed
           $kdf->randomize_seed;

       Generate and set a new random seed/salt.

   register
           File::KDBX::KDF->register($uuid => $package, %args);

       Register a KDF. Registered KDFs can be used to encrypt and decrypt KDBX databases. A KDF's UUID  must  be
       unique  and  musn't  change.  A  KDF  UUID  is written into each KDBX file and the associated KDF must be
       registered with the same UUID in order to decrypt the KDBX file.

       $package should be a Perl package relative to "File::KDBX::KDF::" or prefixed with  a  "+"  if  it  is  a
       fully-qualified package. %args are passed as-is to the KDF's "init" method.

   unregister
           File::KDBX::KDF->unregister($uuid);

       Unregister  a  KDF.  Unregistered KDFs can no longer be used to encrypt and decrypt KDBX databases, until
       reregistered (see "register").

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::KDF(3pm)