1File::KDBX::KDF(3)    User Contributed Perl Documentation   File::KDBX::KDF(3)
2
3
4

NAME

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

VERSION

9       version 0.906
10

DESCRIPTION

12       A KDF (key derivation function) is used in the transformation of a
13       master key (i.e. one or more component keys) to produce the final
14       encryption key protecting a KDBX database. The File::KDBX distribution
15       comes with several pre-registered KDFs ready to go:
16
17       •   "C9D9F39A-628A-4460-BF74-0D08C18A4FEA" - AES
18
19       •   "7C02BB82-79A7-4AC0-927D-114A00648238" - AES (challenge-response
20           variant)
21
22       •   "EF636DDF-8C29-444B-91F7-A9A403E30A0C" - Argon2d
23
24       •   "9E298B19-56DB-4773-B23D-FC3EC6F0A1E6" - Argon2id
25
26       NOTE: If you want your KDBX file to be readable by other KeePass
27       implementations, you must use a UUID and algorithm that they support.
28       From the list above, all are well-supported except the AES challenge-
29       response variant which is kind of a pseudo KDF and isn't usually
30       written into files. All of these are good. AES has a longer track
31       record, but Argon2 has better ASIC resistance.
32
33       You can also "register" your own KDF. Here is a skeleton:
34
35           package File::KDBX::KDF::MyKDF;
36
37           use parent 'File::KDBX::KDF';
38
39           File::KDBX::KDF->register(
40               # $uuid, $package, %args
41               "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
42           );
43
44           sub init { ... } # optional
45
46           sub _transform { my ($key) = @_; ... }
47

ATTRIBUTES

49   uuid
50           $uuid => $kdf->uuid;
51
52       Get the UUID used to determine which function to use.
53
54   seed
55           $seed = $kdf->seed;
56
57       Get the seed (or salt, depending on the function).
58

METHODS

60   new
61           $kdf = File::KDBX::KDF->new(parameters => \%params);
62
63       Construct a new KDF.
64
65   init
66           $kdf = $kdf->init(%attributes);
67
68       Called by "new" to set attributes. You normally shouldn't call this.
69       Returns itself to allow method chaining.
70
71   transform
72           $transformed_key = $kdf->transform($key);
73           $transformed_key = $kdf->transform($key, $challenge);
74
75       Transform a key. The input key can be either a File::KDBX::Key or a raw
76       binary key, and the transformed key will be a raw key.
77
78       This can take awhile, depending on the KDF parameters.
79
80       If a challenge is provided (and the KDF is AES except for the KeePassXC
81       variant), it will be passed to the key so challenge-response keys can
82       produce raw keys. See "raw_key" in File::KDBX::Key.
83
84   randomize_seed
85           $kdf->randomize_seed;
86
87       Generate and set a new random seed/salt.
88
89   register
90           File::KDBX::KDF->register($uuid => $package, %args);
91
92       Register a KDF. Registered KDFs can be used to encrypt and decrypt KDBX
93       databases. A KDF's UUID must be unique and musn't change. A KDF UUID is
94       written into each KDBX file and the associated KDF must be registered
95       with the same UUID in order to decrypt the KDBX file.
96
97       $package should be a Perl package relative to "File::KDBX::KDF::" or
98       prefixed with a "+" if it is a fully-qualified package. %args are
99       passed as-is to the KDF's "init" method.
100
101   unregister
102           File::KDBX::KDF->unregister($uuid);
103
104       Unregister a KDF. Unregistered KDFs can no longer be used to encrypt
105       and decrypt KDBX databases, until reregistered (see "register").
106

BUGS

108       Please report any bugs or feature requests on the bugtracker website
109       <https://github.com/chazmcgarvey/File-KDBX/issues>
110
111       When submitting a bug or request, please include a test-file or a patch
112       to an existing test-file that illustrates the bug or desired feature.
113

AUTHOR

115       Charles McGarvey <ccm@cpan.org>
116

118       This software is copyright (c) 2022 by Charles McGarvey.
119
120       This is free software; you can redistribute it and/or modify it under
121       the same terms as the Perl 5 programming language system itself.
122
123
124
125perl v5.36.1                      2023-09-27                File::KDBX::KDF(3)
Impressum