NAME
Crypt::Sodium::XS::OO::kdf - Secret subkey derivation from a main secret key
SYNOPSIS
use Crypt::Sodium::XS;
my $kdf = Crypt::Sodium::XS->kdf;
my $context = "see notes below about context strings";
my $output_key_length = 32;
my $master_key = $kdf->keygen;
my $subkey_1 = $kdf->derive($master_key, 1, $output_key_length, $context);
my $subkey_2 = $kdf->derive($master_key, 2, $output_key_length, $context);
my $subkey_3 = $kdf->derive($master_key, 54321, $output_key_length, $context);DESCRIPTION
NOTE: Secret keys used to encrypt or sign confidential data have to be chosen from a very large keyspace. However, passwords are usually short, human-generated strings, making dictionary attacks practical. If you are intending to derive keys from a password, see Crypt::Sodium::XS::pwhash instead.
Multiple secret subkeys can be derived from a single high-entropy master key. Given the master key and a numeric key identifier, a subkey can be deterministically computed. However, given a subkey, an attacker cannot compute the master key nor any other subkeys.
CONSTRUCTOR
new
my $kdf = Crypt::Sodium::XS::OO::kdf->new;
my $kdf = Crypt::Sodium::XS::OO::kdf->new(primitive => 'blake2b');
my $kdf = Crypt::Sodium::XS->kdf;Returns a new kdf object for the given primitive. If not given, the default primitive is default.
METHODS
PRIMITIVE
my $kdf = Crypt::Sodium::XS::OO::kdf->new;
my $default_primitive = $kdf->PRIMITIVE;BYTES_MAX
my $subkey_max_length = $kdf->BYTES_MAX;BYTES_MIN
my $subkey_min_length = $kdf->BYTES_MIN;CONTEXTBYTES
my $context_length = $kdf->CONTEXTBYTES;KEYBYTES
my $main_key_length = $kdf->KEYBYTES;derive
my $subkey = $kdf->derive($key, $id, $subkey_len, $context);$key is the master key from which others should be derived.
$id is an unsigned integer signifying the numeric identifier of the subkey which is being derived. The same $key, $id, $length, and $context will always derive the same key.
$subkey_len is the desired length of the subkey output. This can be used to derive a key of the particular length needed for the primitive with which the subkey will be used. It must be between "BYTES_MIN" and "BYTES_MAX" (inclusive).
$context as an arbitrary string which is at least "CONTEXTBYTES" (see warning below). This can be used to create an application-specific tag, such that using the same $key, $id, and $subkey_len can still derive a different subkey.
WARNING: $context must be at least "CONTEXTBYTES" in length. If it is longer than this, only the first "CONTEXTBYTES" bytes will be used. As this gives a limited range of use (application-specific strings might be likely to have the same first 8 bytes), it is recommended to use an arbitrary-length string as the input to a hash function (e.g., "generichash" in Crypt::Sodium::XS::generichash or "shorthash" in Crypt::Sodium::XS::shorthash) and use the output has as $context.
keygen
my $key = $kdf->keygen;SEE ALSO
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel
#sodiumonirc.perl.org.Email the author directly.
AUTHOR
Brad Barden <perlmodules@5c30.org>
COPYRIGHT & LICENSE
Copyright (c) 2022 Brad Barden. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.