]> Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX/KDF.pm
Remove objects from deleted objects when added
[chaz/p5-File-KDBX] / lib / File / KDBX / KDF.pm
1 package File::KDBX::KDF;
2 # ABSTRACT: A key derivation function
3
4 use warnings;
5 use strict;
6
7 use Crypt::PRNG qw(random_bytes);
8 use File::KDBX::Constants qw(:version :kdf);
9 use File::KDBX::Error;
10 use File::KDBX::Util qw(format_uuid);
11 use Module::Load;
12 use Scalar::Util qw(blessed);
13 use namespace::clean;
14
15 our $VERSION = '999.999'; # VERSION
16
17 my %KDFS;
18
19 =method new
20
21 $kdf = File::KDBX::KDF->new(parameters => \%params);
22
23 Construct a new KDF.
24
25 =cut
26
27 sub new {
28 my $class = shift;
29 my %args = @_;
30
31 my $uuid = $args{+KDF_PARAM_UUID} //= delete $args{uuid} or throw 'Missing KDF UUID', args => \%args;
32 my $formatted_uuid = format_uuid($uuid);
33
34 my $kdf = $KDFS{$uuid} or throw "Unsupported KDF ($formatted_uuid)", uuid => $uuid;
35 ($class, my %registration_args) = @$kdf;
36
37 load $class;
38 my $self = bless {KDF_PARAM_UUID() => $uuid}, $class;
39 return $self->init(%args, %registration_args);
40 }
41
42 =method init
43
44 $kdf = $kdf->init(%attributes);
45
46 Called by method to set attributes. You normally shouldn't call this.
47
48 =cut
49
50 sub init {
51 my $self = shift;
52 my %args = @_;
53
54 @$self{keys %args} = values %args;
55
56 return $self;
57 }
58
59 =attr uuid
60
61 $uuid => $kdf->uuid;
62
63 Get the UUID used to determine which function to use.
64
65 =cut
66
67 sub uuid { $_[0]->{+KDF_PARAM_UUID} }
68
69 =attr seed
70
71 $seed = $kdf->seed;
72
73 Get the seed (or salt, depending on the function).
74
75 =cut
76
77 sub seed { die 'Not implemented' }
78
79 =method transform
80
81 $transformed_key = $kdf->transform($key);
82 $transformed_key = $kdf->transform($key, $challenge);
83
84 Transform a key. The input key can be either a L<File::KDBX::Key> or a raw binary key, and the
85 transformed key will be a raw key.
86
87 This can take awhile, depending on the KDF parameters.
88
89 If a challenge is provided (and the KDF is AES except for the KeePassXC variant), it will be passed to the key
90 so challenge-response keys can produce raw keys. See L<File::KDBX::Key/raw_key>.
91
92 =cut
93
94 sub transform {
95 my $self = shift;
96 my $key = shift;
97
98 if (blessed $key && $key->can('raw_key')) {
99 return $self->_transform($key->raw_key) if $self->uuid eq KDF_UUID_AES;
100 return $self->_transform($key->raw_key($self->seed, @_));
101 }
102
103 return $self->_transform($key);
104 }
105
106 sub _transform { die 'Not implemented' }
107
108 =method randomize_seed
109
110 $kdf->randomize_seed;
111
112 Generate a new random seed/salt.
113
114 =cut
115
116 sub randomize_seed {
117 my $self = shift;
118 $self->{+KDF_PARAM_AES_SEED} = random_bytes(length($self->seed));
119 }
120
121 =method register
122
123 File::KDBX::KDF->register($uuid => $package, %args);
124
125 Register a KDF. Registered KDFs can be used to encrypt and decrypt KDBX databases. A KDF's UUID B<must> be
126 unique and B<musn't change>. A KDF UUID is written into each KDBX file and the associated KDF must be
127 registered with the same UUID in order to decrypt the KDBX file.
128
129 C<$package> should be a Perl package relative to C<File::KDBX::KDF::> or prefixed with a C<+> if it is
130 a fully-qualified package. C<%args> are passed as-is to the KDF's L</init> method.
131
132 =cut
133
134 sub register {
135 my $class = shift;
136 my $id = shift;
137 my $package = shift;
138 my @args = @_;
139
140 my $formatted_id = format_uuid($id);
141 $package = "${class}::${package}" if $package !~ s/^\+// && $package !~ /^\Q${class}::\E/;
142
143 my %blacklist = map { File::KDBX::Util::uuid($_) => 1 } split(/,/, $ENV{FILE_KDBX_KDF_BLACKLIST} // '');
144 if ($blacklist{$id} || $blacklist{$package}) {
145 alert "Ignoring blacklisted KDF ($formatted_id)", id => $id, package => $package;
146 return;
147 }
148
149 if (defined $KDFS{$id}) {
150 alert "Overriding already-registered KDF ($formatted_id) with package $package",
151 id => $id,
152 package => $package;
153 }
154
155 $KDFS{$id} = [$package, @args];
156 }
157
158 =method unregister
159
160 File::KDBX::KDF->unregister($uuid);
161
162 Unregister a KDF. Unregistered KDFs can no longer be used to encrypt and decrypt KDBX databases, until
163 reregistered (see L</register>).
164
165 =cut
166
167 sub unregister {
168 delete $KDFS{$_} for @_;
169 }
170
171 BEGIN {
172 __PACKAGE__->register(KDF_UUID_AES, 'AES');
173 __PACKAGE__->register(KDF_UUID_AES_CHALLENGE_RESPONSE, 'AES');
174 __PACKAGE__->register(KDF_UUID_ARGON2D, 'Argon2');
175 __PACKAGE__->register(KDF_UUID_ARGON2ID, 'Argon2');
176 }
177
178 1;
179 __END__
180
181 =head1 DESCRIPTION
182
183 A KDF (key derivation function) is used in the transformation of a master key (i.e. one or more component
184 keys) to produce the final encryption key protecting a KDBX database. The L<File::KDBX> distribution comes
185 with several pre-registered KDFs ready to go:
186
187 =for :list
188 * C<C9D9F39A-628A-4460-BF74-0D08C18A4FEA> - AES
189 * C<7C02BB82-79A7-4AC0-927D-114A00648238> - AES (challenge-response variant)
190 * C<EF636DDF-8C29-444B-91F7-A9A403E30A0C> - Argon2d
191 * C<9E298B19-56DB-4773-B23D-FC3EC6F0A1E6> - Argon2id
192
193 B<NOTE:> If you want your KDBX file to be readable by other KeePass implementations, you must use a UUID and
194 algorithm that they support. From the list above, all are well-supported except the AES challenge-response
195 variant which is kind of a pseudo KDF and isn't usually written into files. All of these are good. AES has
196 a longer track record, but Argon2 has better ASIC resistance.
197
198 You can also L</register> your own KDF. Here is a skeleton:
199
200 package File::KDBX::KDF::MyKDF;
201
202 use parent 'File::KDBX::KDF';
203
204 File::KDBX::KDF->register(
205 # $uuid, $package, %args
206 "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
207 );
208
209 sub init { ... } # optional
210
211 sub _transform { my ($key) = @_; ... }
212
213 =cut
This page took 0.050363 seconds and 4 git commands to generate.