Dogcows Code - chaz/p5-File-KDBX/blob - 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 = '0.906'; # VERSION
  16
  17 my %KDFS;
  18
  19 our %ROUNDS_INFO = (
  20     KDF_UUID_ARGON2D()  => {p => KDF_PARAM_ARGON2_ITERATIONS, d => KDF_DEFAULT_ARGON2_ITERATIONS},
  21     KDF_UUID_ARGON2ID() => {p => KDF_PARAM_ARGON2_ITERATIONS, d => KDF_DEFAULT_ARGON2_ITERATIONS},
  22 );
  23 our $DEFAULT_ROUNDS_INFO = {
  24     p => KDF_PARAM_AES_ROUNDS,
  25     d => KDF_DEFAULT_AES_ROUNDS,
  26 };
  27
  28
  29 sub new {
  30     my $class = shift;
  31     my %args = @_;
  32
  33     my $uuid = $args{+KDF_PARAM_UUID} //= delete $args{uuid} or throw 'Missing KDF UUID', args => \%args;
  34     my $formatted_uuid = format_uuid($uuid);
  35
  36     my $kdf = $KDFS{$uuid} or throw "Unsupported KDF ($formatted_uuid)", uuid => $uuid;
  37     ($class, my %registration_args) = @$kdf;
  38
  39     load $class;
  40     my $self = bless {KDF_PARAM_UUID() => $uuid}, $class;
  41     return $self->init(%args, %registration_args);
  42 }
  43
  44
  45 sub init {
  46     my $self = shift;
  47     my %args = @_;
  48
  49     @$self{keys %args} = values %args;
  50
  51     return $self;
  52 }
  53
  54
  55 sub uuid { $_[0]->{+KDF_PARAM_UUID} }
  56
  57
  58 sub seed { die 'Not implemented' }
  59
  60
  61 sub transform {
  62     my $self = shift;
  63     my $key  = shift;
  64
  65     if (blessed $key && $key->can('raw_key')) {
  66         return $self->_transform($key->raw_key) if $self->uuid eq KDF_UUID_AES;
  67         return $self->_transform($key->raw_key($self->seed, @_));
  68     }
  69
  70     return $self->_transform($key);
  71 }
  72
  73 sub _transform { die 'Not implemented' }
  74
  75
  76 sub randomize_seed {
  77     my $self = shift;
  78     $self->{+KDF_PARAM_AES_SEED} = random_bytes(length($self->seed));
  79 }
  80
  81
  82 sub register {
  83     my $class   = shift;
  84     my $id      = shift;
  85     my $package = shift;
  86     my @args    = @_;
  87
  88     my $formatted_id = format_uuid($id);
  89     $package = "${class}::${package}" if $package !~ s/^\+// && $package !~ /^\Q${class}::\E/;
  90
  91     my %blacklist = map { File::KDBX::Util::uuid($_) => 1 } split(/,/, $ENV{FILE_KDBX_KDF_BLACKLIST} // '');
  92     if ($blacklist{$id} || $blacklist{$package}) {
  93         alert "Ignoring blacklisted KDF ($formatted_id)", id => $id, package => $package;
  94         return;
  95     }
  96
  97     if (defined $KDFS{$id}) {
  98         alert "Overriding already-registered KDF ($formatted_id) with package $package",
  99             id      => $id,
 100             package => $package;
 101     }
 102
 103     $KDFS{$id} = [$package, @args];
 104 }
 105
 106
 107 sub unregister {
 108     delete $KDFS{$_} for @_;
 109 }
 110
 111 BEGIN {
 112     __PACKAGE__->register(KDF_UUID_AES,                     'AES');
 113     __PACKAGE__->register(KDF_UUID_AES_CHALLENGE_RESPONSE,  'AES');
 114     __PACKAGE__->register(KDF_UUID_ARGON2D,                 'Argon2');
 115     __PACKAGE__->register(KDF_UUID_ARGON2ID,                'Argon2');
 116 }
 117
 118 1;
 119
 120 __END__
 121
 122 =pod
 123
 124 =encoding UTF-8
 125
 126 =head1 NAME
 127
 128 File::KDBX::KDF - A key derivation function
 129
 130 =head1 VERSION
 131
 132 version 0.906
 133
 134 =head1 DESCRIPTION
 135
 136 A KDF (key derivation function) is used in the transformation of a master key (i.e. one or more component
 137 keys) to produce the final encryption key protecting a KDBX database. The L<File::KDBX> distribution comes
 138 with several pre-registered KDFs ready to go:
 139
 140 =over 4
 141
 142 =item *
 143
 144 C<C9D9F39A-628A-4460-BF74-0D08C18A4FEA> - AES
 145
 146 =item *
 147
 148 C<7C02BB82-79A7-4AC0-927D-114A00648238> - AES (challenge-response variant)
 149
 150 =item *
 151
 152 C<EF636DDF-8C29-444B-91F7-A9A403E30A0C> - Argon2d
 153
 154 =item *
 155
 156 C<9E298B19-56DB-4773-B23D-FC3EC6F0A1E6> - Argon2id
 157
 158 =back
 159
 160 B<NOTE:> If you want your KDBX file to be readable by other KeePass implementations, you must use a UUID and
 161 algorithm that they support. From the list above, all are well-supported except the AES challenge-response
 162 variant which is kind of a pseudo KDF and isn't usually written into files. All of these are good. AES has
 163 a longer track record, but Argon2 has better ASIC resistance.
 164
 165 You can also L</register> your own KDF. Here is a skeleton:
 166
 167     package File::KDBX::KDF::MyKDF;
 168
 169     use parent 'File::KDBX::KDF';
 170
 171     File::KDBX::KDF->register(
 172         # $uuid, $package, %args
 173         "\x12\x34\x56\x78\x9a\xbc\xde\xfg\x12\x34\x56\x78\x9a\xbc\xde\xfg" => __PACKAGE__,
 174     );
 175
 176     sub init { ... } # optional
 177
 178     sub _transform { my ($key) = @_; ... }
 179
 180 =head1 ATTRIBUTES
 181
 182 =head2 uuid
 183
 184     $uuid => $kdf->uuid;
 185
 186 Get the UUID used to determine which function to use.
 187
 188 =head2 seed
 189
 190     $seed = $kdf->seed;
 191
 192 Get the seed (or salt, depending on the function).
 193
 194 =head1 METHODS
 195
 196 =head2 new
 197
 198     $kdf = File::KDBX::KDF->new(parameters => \%params);
 199
 200 Construct a new KDF.
 201
 202 =head2 init
 203
 204     $kdf = $kdf->init(%attributes);
 205
 206 Called by L</new> to set attributes. You normally shouldn't call this. Returns itself to allow method
 207 chaining.
 208
 209 =head2 transform
 210
 211     $transformed_key = $kdf->transform($key);
 212     $transformed_key = $kdf->transform($key, $challenge);
 213
 214 Transform a key. The input key can be either a L<File::KDBX::Key> or a raw binary key, and the
 215 transformed key will be a raw key.
 216
 217 This can take awhile, depending on the KDF parameters.
 218
 219 If a challenge is provided (and the KDF is AES except for the KeePassXC variant), it will be passed to the key
 220 so challenge-response keys can produce raw keys. See L<File::KDBX::Key/raw_key>.
 221
 222 =head2 randomize_seed
 223
 224     $kdf->randomize_seed;
 225
 226 Generate and set a new random seed/salt.
 227
 228 =head2 register
 229
 230     File::KDBX::KDF->register($uuid => $package, %args);
 231
 232 Register a KDF. Registered KDFs can be used to encrypt and decrypt KDBX databases. A KDF's UUID B<must> be
 233 unique and B<musn't change>. A KDF UUID is written into each KDBX file and the associated KDF must be
 234 registered with the same UUID in order to decrypt the KDBX file.
 235
 236 C<$package> should be a Perl package relative to C<File::KDBX::KDF::> or prefixed with a C<+> if it is
 237 a fully-qualified package. C<%args> are passed as-is to the KDF's L</init> method.
 238
 239 =head2 unregister
 240
 241     File::KDBX::KDF->unregister($uuid);
 242
 243 Unregister a KDF. Unregistered KDFs can no longer be used to encrypt and decrypt KDBX databases, until
 244 reregistered (see L</register>).
 245
 246 =head1 BUGS
 247
 248 Please report any bugs or feature requests on the bugtracker website
 249 L<https://github.com/chazmcgarvey/File-KDBX/issues>
 250
 251 When submitting a bug or request, please include a test-file or a
 252 patch to an existing test-file that illustrates the bug or desired
 253 feature.
 254
 255 =head1 AUTHOR
 256
 257 Charles McGarvey <ccm@cpan.org>
 258
 259 =head1 COPYRIGHT AND LICENSE
 260
 261 This software is copyright (c) 2022 by Charles McGarvey.
 262
 263 This is free software; you can redistribute it and/or modify it under
 264 the same terms as the Perl 5 programming language system itself.
 265
 266 =cut