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

NAME

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

VERSION

9       version 0.906
10

DESCRIPTION

12       A master key is one or more credentials that can protect a KDBX
13       database. When you encrypt a database with a master key, you will need
14       the master key to decrypt it. Keep your master key safe! If someone
15       gains access to your master key, they can open your database. If you
16       forget or lose any part of your master key, all data in the database is
17       lost.
18
19       There are several different types of keys, each implemented as a
20       subclass:
21
22       •   File::KDBX::Key::Password - Password or passphrase, knowledge of a
23           string of characters
24
25       •   File::KDBX::Key::File - Possession of a file ("key file") with a
26           secret
27
28       •   File::KDBX::Key::ChallengeResponse - Possession of a device that
29           responds correctly when challenged
30
31       •   File::KDBX::Key::YubiKey - Possession of a YubiKey hardware device
32           (a type of challenge-response)
33
34       •   File::KDBX::Key::Composite - One or more keys combined as one
35
36       A good master key is produced from a high amount of "entropy"
37       (unpredictability). The more entropy the better.  Combining multiple
38       keys into a Composite key combines the entropy of each individual key.
39       For example, if you have a weak password and you combine it with other
40       keys, the composite key is stronger than the weak password key by
41       itself. (Of course it's much better to not have any weak components of
42       your master key.)
43
44       COMPATIBILITY NOTE: Most KeePass implementations are limited in the
45       types and numbers of keys they support.  Password keys are pretty much
46       universally supported. File keys are pretty well-supported. Many do not
47       support challenge-response keys. If you are concerned about
48       compatibility, you should stick with one of these well-supported
49       configurations:
50
51       •   One password
52
53       •   One key file
54
55       •   Composite of one password and one key file
56

METHODS

58   new
59           $key = File::KDBX::Key->new({ password => $password });
60           $key = File::KDBX::Key->new($password);
61
62           $key = File::KDBX::Key->new({ file => $filepath });
63           $key = File::KDBX::Key->new(\$file);
64           $key = File::KDBX::Key->new(\*FILE);
65
66           $key = File::KDBX::Key->new({ composite => [...] });
67           $key = File::KDBX::Key->new([...]);         # composite key
68
69           $key = File::KDBX::Key->new({ responder => \&responder });
70           $key = File::KDBX::Key->new(\&responder);   # challenge-response key
71
72       Construct a new key.
73
74       The primitive used to construct the key is not saved but is immediately
75       converted to a raw encryption key (see "raw_key").
76
77       A File::KDBX::Key::Composite is somewhat special in that it does retain
78       a reference to its component keys, and its raw key is calculated from
79       its components on demand.
80
81   init
82           $key = $key->init($primitive);
83
84       Initialize a File::KDBX::Key with a new primitive. Returns itself to
85       allow method chaining.
86
87   reload
88           $key = $key->reload;
89
90       Reload a key by re-reading the key source and recalculating the raw
91       key. Returns itself to allow method chaining.
92
93   raw_key
94           $raw_key = $key->raw_key;
95           $raw_key = $key->raw_key($challenge);
96
97       Get the raw encryption key. This is calculated based on the
98       primitive(s). The $challenge argument is for challenge-response type
99       keys and is ignored by other types.
100
101       NOTE: The raw key is sensitive information and so is memory-protected
102       while not being accessed. If you access it, you should memzero or
103       "erase" in File::KDBX::Util it when you're done.
104
105   hide
106           $key = $key->hide;
107
108       Put the raw key in memory protection. Does nothing if the raw key is
109       already in memory protection. Returns itself to allow method chaining.
110
111   show
112           $key = $key->show;
113
114       Bring the raw key out of memory protection. Does nothing if the raw key
115       is already out of memory protection.  Returns itself to allow method
116       chaining.
117
118   is_hidden
119           $bool = $key->is_hidden;
120
121       Get whether or not the key's raw secret is currently in memory
122       protection.
123

BUGS

125       Please report any bugs or feature requests on the bugtracker website
126       <https://github.com/chazmcgarvey/File-KDBX/issues>
127
128       When submitting a bug or request, please include a test-file or a patch
129       to an existing test-file that illustrates the bug or desired feature.
130

AUTHOR

132       Charles McGarvey <ccm@cpan.org>
133

135       This software is copyright (c) 2022 by Charles McGarvey.
136
137       This is free software; you can redistribute it and/or modify it under
138       the same terms as the Perl 5 programming language system itself.
139
140
141
142perl v5.36.1                      2023-09-27                File::KDBX::Key(3)
Impressum